:orphan:

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