# sna2ctl.py

## SYNOPSIS

`sna2ctl.py` [options] FILE

## DESCRIPTION

`sna2ctl.py` generates a control file for a binary (raw memory) file or a SNA, SZX or Z80 snapshot. The control file is written to standard output. When FILE is ‘-’, `sna2ctl.py` reads standard input as a binary file.

## OPTIONS

`-C, --comments`

  Generate instruction comments.

-e, –end ADDR

  Stop at this address. The default end address is 65536. ADDR must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

`-h, --hex`

  Write upper case hexadecimal addresses.

-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, --hex-lower`

  Write lower case hexadecimal addresses.

-m, –map FILE

  Specify a code execution map to use. Code execution maps produced by `rzxplay.py` and `trace.py`, and by the Fuse, SpecEmu, Spud, Zero and Z80 Spectrum emulators are supported.

-o, –org ADDR

  Specify the origin address of a binary file. The default origin address is 65536 minus the length of the file. ADDR must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

-p, –page PAGE

  Specify the page (0-7) of a 128K snapshot to map to 49152-65535.

`-r, --handle-rst`

  Handle RST instruction arguments.

`--show-config`

  Show configuration parameter values.

-s, –start ADDR

  Start at this address. The default start address is 16384 for a snapshot, or the origin address for a raw memory file. ADDR must be a decimal number, or a hexadecimal number prefixed by ‘0x’.

`-V, --version`

  Show the SkoolKit version number and exit.

## CONFIGURATION

`sna2ctl.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:

> Comments:

>   Generate instruction comments (`1`), or don’t (`0`, the default).

> Dictionary:

>   The name of a file containing a list of allowed words, one per line. If specified, a string of characters will be marked as text only if it contains at least one of the words in this file.

> HandleRST:

>   Handle RST instruction arguments (`1`), or don’t (`0`, the default).

> Hex:

>   Write addresses in decimal (`0`, the default), lower case hexadecimal (`1`), or upper case hexadecimal (`2`).

> TextChars:

>   Characters eligible for being marked as text (default: letters, digits, space, and the following non-alphanumeric characters: `!"$%&\'()*+,-./:;<=>?[]`).

> TextMinLengthCode:

>   The minimum length of a string of characters eligible for being marked as text in a block identified as code (default: `12`).

> TextMinLengthData:

>   The minimum length of a string of characters eligible for being marked as text in a block identified as data (default: `3`).

Configuration parameters must appear in a `[sna2ctl]` section. For example, to make `sna2ctl.py` write upper case hexadecimal addresses by default (without having to use the `-h` option on the command line), add the following section to `skoolkit.ini`:

    [sna2ctl]
    Hex=2

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

## EXAMPLES

1. Generate a control file (using rudimentary static code analysis) for `game.z80` named `game.ctl`:

   `sna2ctl.py game.z80 > game.ctl`

2. Generate a control file (using a profile produced by the Fuse emulator) for `game.sna` named `game.ctl`:

   `sna2ctl.py -m game.profile game.sna > game.ctl`