.. index:: macro, .macro, macro language, directive;.macro

Macro language
--------------

The ``.macro`` directive allows you to generate new commands that can
create assembler output. A simple example follows:

.. code-block:: ca65

  foo           .macro  a, b
                .byte   \a
                .word   \b - 1
                .long   0
                .endm

This creates a new macro named ``foo`` which takes two arguments ``a`` and ``b``. To use an argument inside the macro, prefix the parameter name with a backslash ``\``.


Rules for argument substitutions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When looking for argument substitutions, the longest match is
favored. This means if you have parameters called ``a`` and ``aa``,
substituting the longer name is always tried before shorter names,
ignoring the order the parameters are given. As there is no way to
explicitly specify the end of a parameter name inside the body, a
parameter may accidently try to match  characters that comes after the
parameter. A good rule of thumb is to make use of space to separate
entities whenever possible. This also tends to improve readability.

.. index:: macro;local label, local labels inside macro


Use of local labels
^^^^^^^^^^^^^^^^^^^

Each macro expansion will create a new unique context for local labels
inside the macro body. Any previous local label context is restored
after the macro is expanded. Thus, local labels inside a macro will
not clash or interfere with any local labels surrounding the use of
the macro.

This also works when using nested macro expansions. If a macro uses
another macro inside its body, that inner macro expansion will have
its own private local label context, and the previous context of the
outer macro expansion will be restored when the inner macro has been
expanded.

Thus, you are able to do:

.. literalinclude:: macro-local.s
  :language: ca65


Which would create the following list file:

.. literalinclude:: macro-local.lst
  :language: ca65

Arguments with comma
^^^^^^^^^^^^^^^^^^^^

Arguments to a macro are comma separated. This poses a problem in a
situation where you want an argument to contain a comma character.
The ``.argdelim`` directive defines a start and stop character that
can be used to create an argument that contains a comma character.

.. code-block:: ca65

                 .argdelim <>
   access        .macro  arg1, arg2
                 ...
                 .endm

                 access  0, <2,a>

Here ``arg1`` is bound to ``0`` and ``arg2`` is bound to the value
``2,a``.

The delimiter can be either one or two characters and you can pick any
suitable character combination. By default there are no
delimiter characters defined.

If a single character combination is not suitable, you can use two
characters, e.g. ``<-`` and ``->`` which would be defined as follows:

.. code-block:: ca65

                 .argdelim <-->
   access        .macro  arg1, arg2
                 ...
                 .endm

                 access  0, <-2,a->

All delimiter characters are stripped and ``arg2`` is bound to ``2,a``
here as well.
