skool2asm.py¶
SYNOPSIS¶
skool2asm.py [options] FILE
DESCRIPTION¶
skool2asm.py converts a skool file into an ASM file that can be used by a
Z80 assembler. The ASM file is written to standard output. When FILE is ‘-‘,
skool2asm.py reads from standard input.
OPTIONS¶
| -c, --create-labels | |
| Create default labels for unlabelled instructions. | |
| -D, --decimal | Write the disassembly in decimal. |
- -E, –end ADDR
- Stop converting at this address. ADDR must be a decimal number, or a hexadecimal number prefixed by ‘0x’.
- -f, –fixes N
Apply fixes; N may be one of:
0: None (default)1: @ofix only2: @ofix and @bfix3: @ofix, @bfix and @rfix (implies-r)
| -F, --force | Force conversion of the entire skool file, ignoring any @start and
@end directives. |
| -H, --hex | Write the disassembly in hexadecimal. |
- -I, –ini param=value
- Set the value of a configuration parameter (see
CONFIGURATION), overriding any value found inskoolkit.ini. This option may be used multiple times.
| -l, --lower | Write the disassembly in lower case. |
| -p, --package-dir | |
| Show the path to the skoolkit package directory and exit. | |
- -P, –set property=value
- Set the value of an ASM writer property (see
ASM WRITER PROPERTIES). This option may be used multiple times.
| -q, --quiet | Be quiet. This option suppresses both the timing information, and the message about the AsmWriter class being used, but does not suppress warnings. |
| -r, --rsub | Apply safe substitutions (@ssub) and relocatability substitutions (@rsub)
(implies -f 1). |
| --show-config | Show configuration parameter values. |
| -s, --ssub | Apply safe substitutions (@ssub). |
- -S, –start ADDR
- Start converting at this address. ADDR must be a decimal number, or a hexadecimal number prefixed by ‘0x’.
| -u, --upper | Write the disassembly in upper case. |
- –var name=value
- Define a variable that can be used by the
@ifdirective and the#EVAL,#IFand#MAPmacros. This option may be used multiple times.
| -V, --version | Show the SkoolKit version number and exit. |
| -w, --no-warnings | |
| Suppress warnings. | |
- -W, –writer CLASS
- Specify the ASM writer class to use; this will override any @writer directive in the skool file.
CONFIGURATION¶
skool2asm.py will read configuration from a file named skoolkit.ini in
the current working directory or in ~/.skoolkit, if present. The recognised
configuration parameters are:
Address: The format of the default link text for the #Rmacro when the target address has no label (default: ‘’). This format string recognises the replacement fieldaddress. If the format string is blank, the address is formatted exactly as it appears in the skool file (without any$prefix).Base: Convert addresses and instruction operands to hexadecimal ( 16) or decimal (10), or leave them as they are (0, the default).Case: Write the disassembly in lower case ( 1) or upper case (2), or leave it as it is (0, the default).CreateLabels: Create default labels for unlabelled instructions ( 1), or don’t (0, the default).EntryLabel: The format of the default label for the first instruction in a routine or data block (default: L{address}).EntryPointLabel: The format of the default label for an instruction other than the first in a routine or data block (default: {main}_{index}).Quiet: Be quiet ( 1) or verbose (0, the default).Set-property: Set an ASM writer property value (see ASM WRITER PROPERTIES), e.g.Set-bullet=+.Templates: File from which to read custom ASM templates. Warnings: Show warnings ( 1, the default), or suppress them (0).
EntryLabel and EntryPointLabel are standard Python format strings.
EntryLabel recognises the following replacement fields:
address: The address of the routine or data block as it appears in the skool file. location: The address of the routine or data block as an integer.
EntryPointLabel recognises the following replacement fields:
address: The address of the instruction as it appears in the skool file. index: 0 for the first unlabelled instruction in the routine or data block, 1 for the second, etc. location: The address of the instruction as an integer. main: The label of the first instruction in the routine or data block.
Configuration parameters must appear in a [skool2asm] section. For example,
to make skool2asm.py write the disassembly in hexadecimal with a line width
of 120 characters by default (without having to use the -H and -P
options on the command line), add the following section to skoolkit.ini:
[skool2asm]
Base=16
Set-line-width=120
Configuration parameters may also be set on the command line by using the
--ini option. Parameter values set this way will override any found in
skoolkit.ini.
ASM WRITER PROPERTIES¶
Recognised ASM writer property names and their default values are:
bullet: The bullet character(s) to use for list items specified in a #LISTmacro (default:*).comment-width-min: The minimum width of the instruction comment field (default: 10).crlf: 1to use CR+LF to terminate lines, or0to use the system default (default:0).handle-unsupported-macros: How to handle an unsupported macro: 1to expand it to an empty string, or0to exit with an error (default:0).indent: The number of spaces by which to indent instructions (default: 2).instruction-width: The width of the instruction field (default: 23).label-colons: 1to append a colon to labels, or0to leave labels unadorned (default:1).line-width: The maximum width of each line (default: 79).tab: 1to use a tab character to indent instructions, or0to use spaces (default:0).table-border-horizontal: The character to use for the horizontal borders of a table defined by a #TABLEmacro (default:-). If two characters are specified, the first is used for the external borders and the second is used for the internal borders.table-border-join: The character to use for the horizontal and vertical border joins of a table defined by a #TABLEmacro (default:+).table-border-vertical: The character to use for the vertical borders of a table defined by a #TABLEmacro (default:|).table-row-separator: The character used to separate non-header cells in adjacent rows of a table defined by a #TABLEmacro. By default, such cells are not separated.warnings: 1to print any warnings that are produced while writing ASM output (after parsing the skool file), or0to suppress them (default:1).wrap-column-width-min: The minimum width of a wrappable table column (default: 10).
Property values may be set in skoolkit.ini by using the Set-property
configuration parameter (see CONFIGURATION), or on the command line by
using the --set option, or in the skool file by using the @set
directive.
EXAMPLES¶
Convert
game.skoolinto an ASM file namedgame.asm:skool2asm.py game.skool > game.asmConvert
game.skoolinto an ASM file, applying @ssub substitutions and creating default labels for unlabelled instructions in the process:skool2asm.py -s -c game.skool > game.asm