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