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
@startand@enddirectives.- -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