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
@if
directive and the#EVAL
,#IF
and#MAP
macros. 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 #R
macro 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 #LIST
macro (default:*
).comment-width-min: The minimum width of the instruction comment field (default: 10
).crlf: 1
to use CR+LF to terminate lines, or0
to use the system default (default:0
).handle-unsupported-macros: How to handle an unsupported macro: 1
to expand it to an empty string, or0
to 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: 1
to append a colon to labels, or0
to leave labels unadorned (default:1
).line-width: The maximum width of each line (default: 79
).tab: 1
to use a tab character to indent instructions, or0
to use spaces (default:0
).table-border-horizontal: The character to use for the horizontal borders of a table defined by a #TABLE
macro (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 #TABLE
macro (default:+
).table-border-vertical: The character to use for the vertical borders of a table defined by a #TABLE
macro (default:|
).table-row-separator: The character used to separate non-header cells in adjacent rows of a table defined by a #TABLE
macro. By default, such cells are not separated.warnings: 1
to print any warnings that are produced while writing ASM output (after parsing the skool file), or0
to 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.skool
into an ASM file namedgame.asm
:skool2asm.py game.skool > game.asm
Convert
game.skool
into an ASM file, applying @ssub substitutions and creating default labels for unlabelled instructions in the process:skool2asm.py -s -c game.skool > game.asm