# $Id: Macro.pod,v 1.2 2008/12/29 09:51:08 Paulo Custodio Exp $

=head1 NAME

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

=head1 SYNOPSIS

    use CPU::Z80::Assembler::Macro;
    use HOP::Stream;

    my $pp_stream = z80pp($token_stream);

=head1 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 L<HOP::Stream> objects returning sequences of tokens as defined 
in L<CPU::Z80::Assembler::Lexer>.

=head1 EXPORTS

By default the 'z80pp' subroutine is exported.  To disable that, do:

    use CPU::Z80::Assembler::Macro ();

=head1 FUNCTIONS

=head2 z80pp

Takes a L<HOP::Stream> object as input. The stream returns lexical tokens on each 
HOP::Stream::drop() call, as defined in L<CPU::Z80::Assembler::Lexer>.

The output stream contains the same input tokens, except that macro definitions are
slurped and not output, and macro invocations on the input are replaced by the
macro expansion on the output. During the macro expansion, the formal parameters of 
the definition are replaced by the actual arguments, and the defined labels are
renamed to a unique name to allow multiple expansions of the same macro.

=head1 SYNTAX

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

=head1 BUGS and FEEDBACK

See L<CPU::Z80::Assembler>.

=head1 SEE ALSO

L<HOP::Stream>
L<CPU::Z80::Assembler>
L<CPU::Z80::Assembler::Lexer>

=head1 AUTHORS, COPYRIGHT and LICENCE

See L<CPU::Z80::Assembler>.

=cut
