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 only
2: @ofix and @bfix
3: @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 in skoolkit.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 field address. 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, or 0 to use the system default (default: 0).
handle-unsupported-macros:
 How to handle an unsupported macro: 1 to expand it to an empty string, or 0 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, or 0 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, or 0 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), or 0 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

  1. Convert game.skool into an ASM file named game.asm:


    skool2asm.py game.skool > game.asm
  2. 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