Parsing, rendering, and modes

The following subsections explain at a high level the two phases involved in transforming a skool file (and its related ref files, if any exist) into HTML or ASM format by using skool2html.py or skool2asm.py: parsing and rendering.

Parsing

In the first phase, the skool file is parsed. Parsing a skool file entails reading each line of the file, and processing any relevant ASM directives that are found along the way.

After an ASM directive has been processed, it is discarded, so that it cannot be ‘seen’ during the rendering phase. The purpose of the ASM directives is to transform the skool file into something suitable for rendering (in either HTML or ASM format) later on.

Whether a particular ASM directive is processed depends on the mode in which the parsing is being done: HTML mode or ASM mode.

HTML mode

HTML mode is used when the target output format is HTML, as is the case when running skool2html.py. In HTML mode, some ASM directives are ignored because they are irrelevant to the purpose of creating the HTML version of the disassembly. The only ASM directives that are processed in HTML mode are the following:

• @assemble

• @bank

• @bytes

• @defb

• @defs

• @defw

• @expand

• @if

• @keep

• @label

• @remote

• @replace

• @rom

• @bfix block directives

• @isub block directives

• @ofix block directives

• @rfix block directives

• @rsub block directives

• @ssub block directives

The reason that the block directives are processed is that they may define two different versions of a section of code or data: first, a version to include in the output if the corresponding ASM mode (@bfix, @isub, @ofix, @rfix, @rsub, @ssub) is in effect; and second, a version to include in the output if the corresponding ASM mode is not in effect - which will always be the case when parsing in HTML mode.

For example:

@bfix-begin
 32459 CP 26  ; This is a bug; it should be 'CP 27'
@bfix+else
       CP 27  ;
@bfix+end

This instance of a @bfix block directive defines two versions of a section of code. The first version (between @bfix-begin and @bfix+else) will be included in the HTML output, and the second version (between @bfix+else and @bfix+end) will be omitted.

ASM mode

ASM mode is used when the target output format is ASM, as is the case when running skool2asm.py. In ASM mode, all ASM directives are processed.

Rendering

In the second phase, the skool file (stripped of all its ASM directives during the parsing phase) is ‘rendered’ - as either HTML or ASM, depending on the mode.

HTML mode

HTML mode is used to render the skool file (and its related ref file, if one exists) as a bunch of HTML files. During rendering, any skool macros found along the way are expanded to the required HTML markup.

ASM mode

ASM mode is used to render the skool file as a single, assembler-ready ASM file. During rendering, any skool macros found along the way are expanded to some appropriate plain text.