NAME ^

IMCC - Macros

OVERVIEW ^

This document describes the macro layer of imcc

DESCRIPTION ^

The macro support for IMCC was designed to be a drop in replacement for the original assemble.pl macro layer.

One exception is .constant which is PASM mode only. Please use the .const directive for PIR mode. Also note that you have to use .sym inside macros to define symbols, .local is used for local labels.

The addition of the '.' preface will hopefully make things easier to parse, inasmuch as everything within an assembler file that needs to be expanded or processed by the macro engine will have a period ('.') prepended to it.

The macro layer implements constants, macros, local labels and including of files.

A macro definition starts with a line consisting of ".macro", the name for the newly created macro and an optional list of parameters. Thereafter follows the definition of the macro which can span several lines. The definition is ended by ".endm". In the macro definition the formal parameters, preceded by a '.', are valid macros.

  .macro swap (A,B,TEMP) # . marks the directive
    set .TEMP,.A         # . marks the special variable.
    set .A,.B
    set .B,.TEMP
  .endm                  # And . marks the end of the macro.

Macros support labels that are local to a given macro expansion, and the syntax looks something like this:

  .macro SpinForever (Count)
    .local $LOOP: dec .COUNT # ".local $LOOP" defines a local label.
                  branch .$LOOP # Jump to said label.
  .endm

Include this macro as many times as you like, and the branch statement should do the right thing every time. To use a global label, do just as you usually do.

Constants are new, and the syntax looks like:

  .constant PerlHash 6 # Again, . marks the directive

  new P0, .PerlHash # . marks the special variable for expansion.

Several constants are predefined, namely the PMC-Classes.

  .constant Array 0
  .constant PerlUndef 1
  ...

The ".include" statement is followed by a string literal. The file of this name is include literally in the assembly.

The include file is searched in the current directory and in runtime/parrot/include in that order.

Expansion ^

Constant definitions have the form

  .constant name {register}
  .constant name {signed_integer}
  .constant name {signed_float}
  .constant name {"string constant"}
  .constant name {'string constant'}

They don't generate any code, but create a new macro directive .name

Given the line:

  '.constant HelloWorld "Hello, World!"'

one can expand HelloWorld via:

  'print .HelloWorld' # Note the period to indicate a thing to expand.

Some predefined constants exist for your convenience, namely:

  .Array
  .PerlHash
  .PerlArray

and the other PMC types.

The contents of external files can be included by use of the .include macro:

  .include "{filename}"

The contents of the included file are inserted at the point where the .include macro occurs. This means that code like this:

  print "Hello "
  .include "foo.pasm"
  end

where foo.pasm contains:

  print "World \n"

becomes:

  print "Hello "
  print "World \n"
  end

Attempting to include a non-existent file is a non-fatal error.

  .macro name ({arguments?})
  ...
  .endm

Optional arguments are simply identifiers separated by commas. These arguments are matched to instances inside the macro named '.foo'. A simple example follows:

  .macro inc3 (A)
    inc .A # Mark the argument to expand with a '.'.
    inc .A
    inc .A
  .endm

  .inc3(I0) # Expands to the obvious ('inc I0\n') x 3


 parrot