# 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`