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