NAME

CPU::Z80::Assembler::Macro - Macro pre-processor for the Z80 assembler

SYNOPSIS

use CPU::Z80::Assembler::Macro;

my $macro = CPU::Z80::Assembler::Macro->new(
                name   => $name,
                params => \@params_names,
                locals => \%local_labels,
                tokens => \@token_list);
$macro->parse_body($input);
$macro->expand_macro($input);

DESCRIPTION

This module provides a macro pre-processor to parse macro definition statements, and expand macro calls in the token stream. Both the input and output streams are Iterator::Simple::Lookahead objects returning sequences of tokens.

The object created by new() describes one macro. It is used during the parse phase to define the macro object while reading the input token stream.

EXPORTS

None.

FUNCTIONS

new

Creates a new macro definition object, see Class::Struct.

name

Get/set the macro name.

params

Get/set the formal parameter names list.

locals

Get/set the list of local macro labels, stored as a hash.

tokens

Get/set the list of tokens in the macro definition.

parse_body

This method is called with the token input stream pointing at the first token after the macro parameter list, i.e. the '{' or ':' or "\n" character.

It parses the macro body, leaving the input stream after the last token of the macro definition ('endm' or closing '}'), with all the "\n" characters of the macro defintion pre-pended, and filling in locals() and tokens().

expand_macro

This method is called with the input stream pointing at the first token after the macro name in a macro call. It parses the macro arguments, if any and expands the macro call, inserting the expanded tokens in the input stream.

parse_macro_arguments

This method is called with the input stream pointing at the first token after the macro name in a macro call. It parses the macro arguments, leaves the input stream after the macro call, and returns an hash reference mapping formal argument names to list of tokens in the actual parameters.

The arguments are list of tokens separated by ','. An argument can be enclosed in braces '{' '}' to allow ',' to be passed - the braces are not part of the argument value.

SYNTAX

Macros

Macros are created thus. This example creates an "instruction" called MAGIC that takes two parameters:

MACRO MAGIC param1, param2 {
    LD param1, 0
    BIT param2, L
    label = 0x1234
    ... more real instructions go here.
}

Within the macro, param1, param2 etc will be replaced with whatever parameters you pass to the macro. So, for example, this:

MAGIC HL, 2

Is the same as:

LD HL, 0
BIT 2, L
...

Any labels that you define inside a macro are local to that macro. Actually they're not but they get renamed to _macro_NN_... so that they effectively *are* local.

There is an alternative syntax, for compatibility with other assemblers, with exactly the same effect.

MACRO MAGIC param1, param2
    LD param1, 0
    BIT param2, L
    label = 0x1234
    ... more real instructions go here.
ENDM

A ',' can be passed as part of a macro argument, by enclosing the arguments between {braces}.

MACRO PAIR x {
    LD x
}
PAIR {A,B}

expands to:

LD A,B

BUGS and FEEDBACK

See CPU::Z80::Assembler.

AUTHORS, COPYRIGHT and LICENCE