tagged release 0.6.4

[parrot.git] / docs / pdds / draft / pdd19_pir.pod

# Copyright (C) 2007, The Perl Foundation.
# $Id$

=head1 NAME

docs/pdds/pdd19_pir.pod - Parrot Intermediate Representation

=head1 VERSION

$Revision$


=head1 ABSTRACT

This document outlines the architecture and core syntax of the Parrot
Intermediate Representation (PIR).

This document describes PIR, a stable, middle-level language for both
compiler and human to target on.

=head1 DESCRIPTION

PIR is a stable, middle-level language intended both as a target for the
generated output from high-level language compilers, and for human use
developing core features and extensions for Parrot.

=head1 IMPLEMENTATION

=head2 Basic Syntax

A valid PIR program consists of a sequence of statements, directives, comments
and empty lines.

=head3 Statements

A statement starts with an optional label, contains an instruction, and is
terminated by a newline (<NL>). Each statement must be on its own line.

  [label:] [instruction] <NL>

An instruction may be either a low-level opcode or a higher-level PIR
operation, such as a subroutine call, a method call, a directive, or PIR
syntactic sugar.

=head3 Directives

A directive provides information for the PIR compiler that is outside the
normal flow of executable statements. Directives are all prefixed with a ".",
as in C<.local> or C<.sub>.

=head3 Comments

Comments start with C<#> and last until the following newline. PIR also allows
comments in Pod format. Comments, Pod content, and empty lines are ignored.

=head3 Identifiers

Identifiers start with a letter or underscore, then may contain additionally
letters, digits, and underscores. Identifiers don't have any limit on length
at the moment, but some sane-but-generous length limit may be imposed in the
future (256 chars, 1024 chars?). The following examples are all valid
identifiers.

    a
    _a
    A42

Opcode names are not reserved words in PIR, and may be used as variable names.
For example, you can define a local variable named C<print>.  [See RT #24251]

{{ NOTE: The use of C<::> in identifiers is deprecated. [See RT #48735] }}

=head3 Labels

A label declaration consists of a label name followed by a colon. A label name
conforms to the standard requirements for identifiers. A label declaration may
occur at the start of a statement, or stand alone on a line, but always within
a compilation unit.

A reference to a label consists of only the label name, and is generally used
as an argument to an instruction or directive.

A PIR label is accessible only in the compilation unit where it's defined. A
label name must be unique within a compilation unit, but it can be reused in
other compilation units.

  goto label1
     ...
  label1:

=head3 Registers and Variables

There are three ways of referencing Parrot's registers. The first is direct
access to a specific register by name In, Sn, Nn, Pn. The second is through a
temporary register variable $In, $Sn, $Nn, $Pn. I<n> consists of digit(s)
only.  There is no limit on the size of I<n>.

The third syntax for accessing registers is through named local variables
declared with C<.local>.

  .local pmc foo

The type of a named variable can be C<int>, C<num>, C<string> or C<pmc>,
corresponding to the types of registers. No other types are used. [See
RT#42769]

The difference between direct register access and register variables or local
variables is largely a matter of allocation. If you directly reference C<P99>,
Parrot will blindly allocate 100 registers for that compilation unit. If you
reference C<$P99> or a named variable C<foo>, on the other hand, Parrot will
intelligently allocate a literal register in the background. So, C<$P99> may
be stored in C<P0>, if it is the only register in the compilation unit.

=head2 Constants

Constants may be used in place of registers or variables. A constant is not
allowed on the left side of an assignment, or in any other context where the
variable would be modified.

=over 4

=item 'single-quoted string constant'

Are delimited by single-quotes (C<'>). They are taken to be ASCII encoded. No
escape sequences are processed.

=item "double-quoted string constants"

Are delimited by double-quotes (C<">). A C<"> inside a string must be escaped
by C<\>.  Only 7-bit ASCII is accepted in string constants; to use characters
outside that range, specify an encoding in the way below.

=item <<"heredoc",  <<'heredoc'

Heredocs work like single or double quoted strings. All lines up to
the terminating delimiter are slurped into the string. The delimiter
has to be on its own line, at the beginning of the line and with no
trailing whitespace.

Assignment of a heredoc:

  $S0 = <<"EOS"
  ...
 EOS

A heredoc as an argument:

  function(<<"END_OF_HERE", arg)
  ...
 END_OF_HERE

  .return(<<'EOS')
  ...
 EOS

  .yield(<<'EOS')
  ...
 EOS

You may have multiple heredocs within a single statement or directive:

   function(<<'INPUT', <<'OUTPUT', 'some test')
   ...
 INPUT
   ...
 OUTPUT

=item charset:"string constant"

Like above with a character set attached to the string. Valid character
sets are currently: C<ascii> (the default), C<binary>, C<unicode>
(with UTF-8 as the default encoding), and C<iso-8859-1>.

=back

=head2 String escape sequences

Inside double-quoted strings the following escape sequences are processed.

  \xhh        1..2 hex digits
  \ooo        1..3 oct digits
  \cX         control char X
  \x{h..h}    1..8 hex digits
  \uhhhh      4 hex digits
  \Uhhhhhhhh  8 hex digits
  \a, \b, \t, \n, \v, \f, \r, \e, \\

=over 4

=item encoding:charset:"string constant"

Like above with an extra encoding attached to the string. For example:

  set S0, utf8:unicode:"«"

The encoding and charset gets attached to the string, no further processing
is done, specifically escape sequences are not honored.

=item numeric constants

C<0x> and C<0b> denote hex and binary constants respectively.

=back

=head2 Directives

=over 4

=item .local <type> <identifier> [:unique_reg]

Define a local name I<identifier> for this compilation unit with the given
I<type>. You can define multiple identifiers of the same type by separating
them with commas:

  .local int i, j

The optional C<:unique_reg> modifier will force the register allocator to
associate the identifier with a unique register for the duration of the
compilation unit.

=item .lex <string constant>, <reg>

Declare a lexical variable that is an alias for a PMC register. For example,
given this preamble:

    .lex "$a", $P0
    $P1 = new 'Integer'

    These two opcodes have an identical effect:

    $P0 = $P1
    store_lex "$a", $P1

    And these two opcodes also have an identical effect:

    $P1 = $P0
    $P1 = find_lex "$a"

=item .const <type> <identifier> = <const>

{{ PROPOSAL: add
   .const <string constant> <identifier> = <const>
   as an alternative to allow ".const 'Sub' ... "
}}

Define a constant named I<identifier> of type I<type> and assign value
I<const> to it. The constant is stored in the constant table of the current
bytecode file.

=item .globalconst <type> <identifier> = <const>

As C<.const> above, but the defined constant is globally accessible.

=item .namespace <identifier> [deprecated: See RT #48737]

Open a new scope block. This "namespace" is not the same as the
.namespace [ <identifier> ] syntax, which is used for storing subroutines
in a particular namespace in the global symbol table.
This directive is useful in cases such as (pseudocode):

  local x = 1;
  print(x);       # prints 1
  do              # open a new namespace/scope block
    local x = 2;  # this x hides the previous x
    print(x);     # prints 2
  end             # close the current namespace
  print(x);       # prints 1 again

All types of common language constructs such as if, for, while, repeat and
such that have nested scopes, can use this directive.

{{ NOTE: this variation of C<.namespace> and C<.endnamespace> are deprecated.
They were a hackish attempt at implementing scopes in Parrot, but didn't
actually turn out to be useful.}}

=item .endnamespace <identifier> [deprecated: See RT #48737]

Closes the scope block that was opened with .namespace <identifier>.

=item .namespace [ <identifier> ; <identifier> ]

   .namespace [ <key>? ]

   key: <identifier> [';' <identifier>]*

Defines the namespace from this point onwards.  By default the program is not
in any namespace.  If you specify more than one, separated by semicolons, it
creates nested namespaces, by storing the inner namespace object in the outer
namespace's global pad.

You can specify the root namespace by using empty brackets, such as:

    .namespace [ ]

The brackets are not optional, although the string inside them is.

{{ NOTE: currently the brackets *are* optional. TODO: make decision whether
   we want the brackets optional. }}


=item .pragma n_operators

Convert arithmethic infix operators to n_infix operations. The unary opcodes
C<abs>, C<not>, C<bnot>, C<bnots>, and C<neg> are also changed to use a C<n_>
prefix.

 .pragma n_operators 1
 .sub foo
   ...
   $P0 = $P1 + $P2           # n_add $P0, $P1, $P2
   $P2 = abs $P0             # n_abs $P2, $P0

=item .loadlib "lib_name"

Load the given library at compile time, that is, as soon that line is
parsed.  See also the C<loadlib> opcode, which does the same at run time.

A library loaded this way is also available at runtime, as if it has been
loaded again in C<:load>, so there is no need to call C<loadlib> at runtime.

=item .HLL <hll_name>, <hll_lib>

Define the HLL for the current file. Takes two string constants. If the string
I<hll_lib> isn't empty this compile time pragma also loads the shared lib for
the HLL, so that integer type constants are working for creating new PMCs.

{{ PROPOSAL: make the ",<hll_lib>" part optional, so you don't have to
   specify an empty string for the library.
   (Alternatively, make this two different directives: .HLL_name, .HLL_lib)
}}

=item .HLL_map <core_type>, <user_type>

{{ PROPOSAL: make the ',' an "->", "=>", "=", for instance, so it's easier
   to remember what argument comes first, the core type or the user type.
}}

Whenever Parrot has to create PMCs inside C code on behalf of the running
user program it consults the current type mapping for the executing HLL
and creates a PMC of type I<user_type> instead of I<core_type>, if such
a mapping is defined. I<core_type> and I<user_type> may be any valid string
constant.

For example, with this code snippet ...

  .loadlib 'dynlexpad'

  .HLL "Foo", ""
  .HLL_map 'LexPad', 'DynLexPad'

  .sub main :main
    ...

... all subroutines for language I<Foo> would use a dynamic lexpad pmc.

{{ PROPOSAL: stop using integer constants for types RT#45453 }}

=item .sub

  .sub <identifier> [:<flag> ...]
  .sub <quoted string> [:<flag> ...]

Define a compilation unit. All code in a PIR source file must be defined in a
compilation unit. See the section C<Subroutine flags> for
available flags.  Optional flags are a list of I<flag>, separated by empty
spaces.

The name of the sub may be either a bare identifier or a quoted string
constant. Bare identifiers must be valid PIR identifiers (see L<Identifiers>
above), but string sub names can contain any characters, including characters
from different character sets (see L<Constants> above).

Always paired with C<.end>.

=item .end

End a compilation unit. Always paired with C<.sub>.

=item .line <integer>, <string>

Set the line number and filename to the value specified. This is useful in
case the PIR code is generated from some source file, and any error messages
should print the source file, not the line number and filename of the
generated file.

{{ DEPRECATION NOTE: was C<<#line <integer> <string>>>. See [RT#45857],
[RT#43269], and [RT#47141]. }}

=back

=head3 Subroutine flags

=over 4

=item :main

Define "main" entry point to start execution.  If multiple subroutines are
marked as B<:main>, the B<last> marked subroutine is used.  Only the first
file loaded or compiled counts; subs marked as B<:main> are ignored by the
B<load_bytecode> op.

=item :load

Run this subroutine when loaded by the B<load_bytecode> op (i.e. neither in
the initial program file nor compiled from memory).  This is complementary to
what B<:init> does (below); to get both behaviours, use B<:init :load>.  If
multiple subs have the B<:load> pragma, the subs are run in source code order.

=item :init

Run the subroutine when the program is run directly (that is, not loaded as a
module), including when it is compiled from memory.  This is complementary to
what B<:load> does (above); to get both behaviours, use B<:init :load>.

=item :anon

Do not install this subroutine in the namespace. Allows the subroutine
name to be reused.

=item :multi(Type1, Type2...)

Engage in multiple dispatch with the listed types.
See L<docs/pdds/pdd27_multi_dispatch.pod> for more information on the
multiple dispatch system.

=item :immediate

Execute this subroutine immediately after being compiled, which is analogous
to C<BEGIN> in Perl 5.

In addition, if the sub returns a PMC value, that value replaces the sub in
the constant table of the bytecode file.  This makes it possible to build
constants at compile time, provided that (a) the generated constant can be
computed at compile time (i.e. doesn't depend on the runtime environment), and
(b) the constant value is of a PMC class that supports saving in a bytecode
file [need a freeze/thaw reference].

For example, C<examples/shootout/revcomp.pir> contains the following (slightly
abbreviated) definition:

    .sub tr_00_init :immediate
    .local pmc tr_array
    tr_array = new 'FixedIntegerArray'
    tr_array = 256
    ## [code to initialize tr_array omitted.]
    .return (tr_array)
    .end

This code is run at compile time, and the returned C<tr_array> is stored
in the bytecode file in place of the sub.  Other subs may then do:

    .const .Sub tr_00 = 'tr_00_init'

in order to fetch the constant.

=item :postcomp

Execute immediately after being compiled, but only if the subroutine is in the
initial file (i.e. not in PIR compiled as result of a C<load_bytecode>
instruction from another file).

As an example, suppose file C<main.pir> contains:

    .sub main
        load_bytecode "foo.pir"
    .end

and the file C<foo.pir> contains:

    .sub foo :immediate
        print "42"
    .end

    .sub bar :postcomp
        print "43"
    .end

Executing C<foo.pir> will run both C<foo> and C<bar>.  On the other hand,
executing C<main.pir> will run only C<foo>.  If C<foo.pir> is compiled to
bytecode, only C<foo> will be run, and loading C<foo.pbc> will not run either
C<foo> or C<bar>.

=item :method

The marked C<.sub> is a method. In the method body, the object PMC
can be referred to with C<self>.

=item :vtable

The marked C<.sub> overrides a v-table method. By default, a sub with the same
name as a v-table method does not override the v-table method. To specify that
there should be no namespace entry (that is, it just overrides the v-table
method but is callable as a normal method), use B<:vtable :anon>. To give the
v-table method a different name, use B<:vtable("...")>. For example, to have
the method B<ToString> also be the v-table method B<get_string>), use
B<:vtable("get_string")>.

When the B<:vtable> flag is set, the object PMC cn be referred to with 
C<self>, as with the B<:method> flag.


=item :outer(subname)

The marked C<.sub> is lexically nested within the sub known by B<subname>.

=item :lexid( <string_constant> )

Identifies the subroutine by the specified string.

{{ TODO: explain purpose and details of this flag. }}

=back


=head3 Directives used for Parrot calling conventions.

{{ A bit of a radical idea, but now would be the time to decide on this:
   Remove the whole "long-style" invocation syntax altogether.
   Only allow the short version.
   As PIR is typically being generated, and hopefully by PCT-based
   compilers, there seems to be no real use for too much syntactic
   sugar. Just a thought.
}}

=over 4

=item .begin_call and .end_call

Directives to start and end a subroutine invocation, respectively.

=item .begin_return and .end_return

Directives to start and end a statement to return values.

=item .begin_yield and .end_yield

Directives to start and end a statement to yield values.

=item .call

Takes either 2 arguments: the sub and the return continuation, or the
sub only. For the latter case an B<invokecc> gets emitted. Providing
an explicit return continuation is more efficient, if its created
outside of a loop and the call is done inside a loop.

=item .invocant

Directive to specify the object for a method call. Use it in combination
with C<.meth_call>.

=item  .meth_call

Directive to do a method call. It calls the specified method on the object
that was specified with the C<.invocant> directive.

=item .nci_call

Directive to make a call through the Native Calling Interface (NCI).
The specified subroutine must be loaded using the <dlfunc> op that takes
the library, function name and function signature as arguments.
See L<docs/pdds/pdd16_native_call> for details.

=item .return <var> [:<flag>]*

Between C<.begin_return> and C<.end_return>, specify one or
more of the return value(s) of the current subroutine.  Available
flags: C<:flat>, C<:named>.

=item .arg <var> [:<flag>]*

Between C<.begin_call> and C<.call>, specify an argument to be
passed.  Available flags: C<:flat>, C<:named>.

=item .result <var> [:<flag>]*

Between C<.call> and C<.end_call>, specify where one or more return
value(s) should be stored.  Available flags:
C<:slurpy>, C<:named>, C<:optional>, and C<:opt_flag>.

=back

=head3 Directives for subroutine parameters

=over 4

=item .param <type> <identifier> [:<flag>]*

At the top of a subroutine, declare a local variable, in the manner
of C<.local>, into which parameter(s) of the current subroutine should
be stored. Available flags:
C<:slurpy>, C<:named>, C<:optional>, C<:opt_flag> and C<:unique_reg>.

=item .param <type> "<identifier>" => <identifier> [:<flag>]*

Define a named parameter. This is syntactic sugar for:

 .param <type> <identifier> :named("<identifier>")

=back

=head3 Parameter Passing and Getting Flags

See L<PDD03|pdds/pdd03_calling_conventions.pod> for a description of
the meaning of the flag bits C<SLURPY>, C<OPTIONAL>, C<OPT_FLAG>,
and C<FLAT>, which correspond to the calling convention flags
C<:slurpy>, C<:optional>, C<:opt_flag>, and C<:flat>.


=head3 Catching Exceptions

Using the C<push_eh> op you can install an exception handler. If an exception
is thrown, Parrot will execute the installed exception handler. In order to
retrieve the thrown exception, use the C<.get_results> directive. This
directive always takes 2 arguments: an exception object and a message string.

{{ Wouldn't it be more useful to make this flexible, or at least only the
exception object? The message can be retrieved from the exception object. }}

   push_eh handler
   ...
 handler:
   .local pmc exception
   .local string message
   .get_results (exception, message)
   ...

This is syntactic sugar for the C<get_results> op, but any flags set on the
targets will be handled automatically by the PIR compiler.
The C<.get_results> directive must be the first instruction of the exception
handler; only declarations (.lex, .local) may come first.

=head2 Syntactic Sugar

Any PASM opcode is a valid PIR instruction. In addition, PIR defines some
syntactic shortcuts. These are provided for ease of use by humans producing
and maintaing PIR code.

=over 4

=item goto <identifier>

C<branch> to I<identifier> (label or subroutine name).

Examples:

  goto END

=item if <var> goto <identifier>

If I<var> evaluates as true, jump to the named I<identifier>. Translate to
C<if var, identifier>.

=item unless <var> goto <identifier>

Unless I<var> evaluates as true, jump to the named I<identifier>. Translate
to C<unless var, identifier>.

=item if null <var> goto <identifier>

If I<var> evaluates as null, jump to the named I<identifier>. Translate to
C<if_null var, identifier>.

=item unless null <var> goto <identifier>

Unless I<var> evaluates as null, jump to the named I<identifier>. Translate
to C<unless_null var, identifier>.

=item if <var1> <relop> <var2> goto <identifier>

The I<relop> can be: C<E<lt>, E<lt>=, ==, != E<gt>= E<gt>> which translate
to the PASM opcodes C<lt>, C<le>, C<eq>, C<ne>, C<ge> or C<gt>. If
I<var1 relop var2> evaluates as true, jump to the named I<identifier>.

=item unless <var1> <relop> <var2> goto <identifier>

The I<relop> can be: C<E<lt>, E<lt>=, ==, != E<gt>= E<gt>> which translate
to the PASM opcodes C<lt>, C<le>, C<eq>, C<ne>, C<ge> or C<gt>. Unless
I<var1 relop var2> evaluates as true, jump to the named I<identifier>.

=item <var1> = <var2>

Assign a value. Translates to C<set var1, var2>.

=item <var1> = <unary> <var2>

The unaries C<!>, C<-> and C<~> generate C<not>, C<neg> and C<bnot> ops.

=item <var1> = <var2> <binary> <var3>

The binaries C<+>, C<->, C<*>, C</>, C<%> and C<**> generate
C<add>, C<sub>, C<mul>, C<div>, C<mod> and C<pow> arithmetic ops.
binary C<.> is C<concat> and only valid for string arguments.

C<E<lt>E<lt>> and C<E<gt>E<gt>> are arithmetic shifts C<shl> and C<shr>.
C<E<gt>E<gt>E<gt>> is the logical shift C<lsr>.

C<&&>, C<||> and C<~~> are logic C<and>, C<or> and C<xor>.

C<&>, C<|> and C<~> are binary C<band>, C<bor> and C<bxor>.

{{PROPOSAL: Change description to support logic operators (comparisons) as
implemented (and working) in imcc.y.}}

=item <var1> <op>= <var2>

This is equivalent to
C<E<lt>var1E<gt> = E<lt>var1E<gt> E<lt>opE<gt> E<lt>var2E<gt>>. Where
I<op> is called an assignment operator and can be any of the following
binary operators described earlier: C<+>, C<->, C<*>, C</>, C<%>, C<.>,
C<&>, C<|>, C<~>, C<E<lt>E<lt>>, C<E<gt>E<gt>> or C<E<gt>E<gt>E<gt>>.

=item <var> = <var> [ <var> ]

This generates either a keyed C<set> operation or C<substr var, var,
var, 1> for string arguments and an integer key.

=item <var> = <var> [ <key> ]

{{ NOTE: keyed assignment is still valid in PIR, but the C<..> notation in
keys is deprecated [See RT #48561], so this syntactic sugar for slices is also
deprecated. See the (currently experimental) C<slice> opcode instead. }}

where C<key> is:

 <var1> .. <var2>

returns a slice defined starting at C<var1> and ending at C<var2>.

 .. <var2>

returns a slice starting at the first element, and ending at C<var2>.

 <var1> ..

returns a slice starting at C<var1> to the end of the array.

see src/pmc/slice.pmc
and t/pmc/slice.t.

=item <var> [ <var> ] = <var>

A keyed C<set> operation.

{{ DEPRECATION NOTE: this syntactic sugar will no longer be used for the
assign C<substr> op with a length of 1. }}

=item <var> = <opcode> <arguments>

All opcodes can use this PIR syntactic sugar. The first argument for the
opcode is placed before the C<=>, and all remaining arguments go after the
opcode name. For example:

  new $P0, 'Type'

becomes:

  $P0 = new 'Type'

=item global "string" = <var>

{{ DEPRECATED: op store_global was deprecated }}

=item <var> = global "string"

{{ DEPRECATED: op find_global was deprecated }}

=item ([<var1> [:<flag1> ...], ...]) = <var2>([<arg1> [:<flag2> ...], ...])

This is short for:

  .begin_call
  .arg <arg1> <flag2>
  ...
  .call <var2>
  .result <var1> <flag1>
  ...
  .end_call

=item <var> = <var>([arg [:<flag> ...], ...])

=item <var>([arg [:<flag> ...], ...])

=item <var>."_method"([arg [:<flag> ...], ...])

=item <var>._method([arg [:<flag> ...], ...])

Function or method call. These notations are shorthand for a longer PCC
function call. I<var> can denote a global subroutine, a local I<identifier> or
a I<reg>.

{{We should review the (currently inconsistent) specification of the
method name. Currently it can be a bare word, a quoted string or a
string register. See #45859.}}

=item .return ([<var> [:<flag> ...], ...])

Return from the current compilation unit with zero or more values.

The surrounded parentheses are mandatory. Besides making sequence
break more conspicuous, this is necessary to distinguish this syntax
from other uses of the C<.return> directive that will be probably
deprecated.

=item .return <var>(args)

=item .return <var>."somemethod"(args)

=item .return <var>.somemethod(args)

Tail call: call a function or method and return from the sub with the
function or method call return values.

Internally, the call stack doesn't increase because of a tail call, so
you can write recursive functions and not have stack overflows.

=back

=head2 Assignment and Morphing

The C<=> syntactic sugar in PIR, when used in the simple case of:

  <var1> = <var2>

directly corresponds to the C<set> opcode. So, two low-level arguments (int,
num, or string registers, variables, or constants) are a direct C assignment,
or a C-level conversion (int cast, float cast, a string copy, or a call to one
of the conversion functions like C<string_to_num>).

A PMC source with a low-level destination, calls the C<get_integer>,
C<get_number>, or C<get_string> vtable function on the PMC. A low-level source
with a PMC destination calls the C<set_integer_native>, C<set_number_native>,
or C<set_string_native> vtable function on the PMC (assign to value
semantics).  Two PMC arguments are a direct C assignment (assign to container
semantics).

For assign to value semantics for two PMC arguments use C<assign>, which calls
the C<assign_pmc> vtable function.


{{ NOTE: response to the question:

    <pmichaud>  I don't think that 'morph' as a method call is a good idea
    <pmichaud>  we need something that says "assign to value" versus
        "assign to container"
    <pmichaud>  we can't eliminate the existing 'morph' opcode until we have a
        replacement

}}


=head2 Macros

This section describes the macro layer of the PIR language. The macro layer of
the PIR compiler handles the following directives:

=over 4

=item * C<.include> "<filename>"

The C<.include> directive takes a string argument that contains the
name of the PIR file that is included. The contents of the included
file are inserted as if they were written at the point where the
C<.include> directive occurs.

The include file is searched for in the current directory and in
runtime/parrot/include, in that order. The first file of that name to be found
is included.

{{ Check the include directive's search order and whether it's complete }}

=item * C<.macro> <identifier> [<parameters>]

The C<.macro> directive starts the a macro definition named by the specified
identifier. The optional parameter list is a comma-separated list of
identifiers, enclosed in parentheses.  See C<.endm> for ending the macro
definition.

=item * C<.endm>

Closes a macro definition.

=item * C<.macro_const> <identifier> (<literal>|<reg>)

 .macro_const   PI  3.14

The C<.macro_const> directive is a special type of macro; it allows the user
to use a symbolic name for a constant value. Like C<.macro>, the substitution
occurs at compile time. It takes two arguments (not comma separated), the
first is an identifier, the second a constant value or a register.

=back

The macro layer is completely implemented in the lexical analysis phase.
The parser does not know anything about what happens in the lexical
analysis phase.

When the C<.include> directive is encountered, the specified file is opened
and the following tokens that are requested by the parser are read from
that file.

A macro expansion is a dot-prefixed identifier. For instance, if a macro
was defined as shown below:

 .macro foo(bar)
 ...
 .endm

this macro can be expanded by writing C<.foo(42)>. The body of the macro
will be inserted at the point where the macro expansion is written.

A C<.macro_const> expansion is more or less the same as a C<.macro> expansion,
except that a constant expansion cannot take any arguments, and the
substitution of a C<.macro_const> contains no newlines, so it can be used
within a line of code.

=head3 Macro parameter list

The parameter list for a macro is specified in parentheses after the name of
the macro. Macro parameters are not typed.

 .macro foo(bar, baz, buz)
 ...
 .endm

The number of arguments in the call to a macro must match the number of
parameters in the macro's parameter list. Macros do not perform multidispatch,
so you can't have two macros with the same name but different parameters.
Calling a macro with the wrong number of arguments gives the user an error.

If a macro defines no parameter list, parentheses are optional on both the
definition and the call.  This means that a macro defined as:

 .macro foo
 ...
 .endm

can be expanded by writing either C<.foo> or C<.foo()>. And a macro definition
written as:

 .macro foo()
 ...
 .endm

can also be expanded by writing either C<.foo> or C<.foo()>.

{{ NOTE: this is a change from the current implementation, which requires the
definition and call of a zero-parameter macro to match in the use of
parentheses. }}

=over

=item * Heredoc arguments

Heredoc arguments are not allowed when expanding a macro. This means that
the following is not allowed:

   .macro foo(bar)
   ...
   .endm

   .foo(<<'EOS')
 This is a heredoc
    string.

 EOS

{{ NOTE: This is likely because the parsing of heredocs happens later than the
preprocessing of macros. Might be nice if we could parse heredocs at the macro
level, but not a high priority. compilers/pirc/new can do this. }}

Using braces, { }, allows you to span multiple lines for an argument.
See runtime/parrot/include/hllmacros.pir for examples and possible usage.
A simple example is this:

 .macro foo(a,b)
   .a
   .b
 .endm

 .sub main
   .foo({ print "1"
          print "2"
        }, {
          print "3"
          print "4"
        })
 .end

This will expand the macro C<foo>, after which the input to the PIR parser is:

 .sub main
   print "1"
   print "2"
   print "3"
   print "4"
 .end

which will result in the output:

 1234

=back

=head3 Unique local labels

Within the macro body, the user can declare a unique label identifier using
the value of a macro parameter, like so:

  .macro foo(a)
  ...
 .label $a:
  ...
  .endm


=head3 Unique local variables

Within the macro body, the user can declare a local variable with a unique
name.

  .macro foo()
  ...
  .macro_local int b
  ...
  .b = 42
  print .b # prints the value of the unique variable (42)
  ...
  .endm

The C<.macro_local> directive declares a local variable with a unique name in
the macro. When the macro C<.foo()> is called, the resulting code that is
given to the parser will read as follows:

  .sub main
    .local int local__foo__b__2
    ...
    local__foo__b__2 = 42
    print local__foo__b__2

  .end

The user can also declare a local variable with a unique name set to the
symbolic value of one of the macro parameters.

  .macro foo(b)
  ...
  .macro_local int $b
  ...
  .$b = 42
  print .$b # prints the value of the unique variable (42)
  print .b  # prints the value of parameter "b", which is
            # also the name of the variable.
  ...
  .endm

So, the special C<$> character indicates whether the symbol is interpreted as
just the value of the parameter, or that the variable by that name is meant.
Obviously, the value of C<b> should be a string.

The automatic name munging on C<.macro_local> variables allows for using
multiple macros, like so:

  .macro foo(a)
  .macro_local int $a
  .endm

  .macro bar(b)
  .macro_local int $b
  .endm

  .sub main
    .foo("x")
    .bar("x")
  .end

This will result in code for the parser as follows:

  .sub main
    .local int local__foo__x__2
    .local int local__bar__x__4
  .end

Each expansion is associated with a unique number; for labels declared with
C<.macro_label> and locals declared with C<.macro_local> expansions, this
means that multiple expansions of a macro will not result in conflicting
label or local names.

=head3 Ordinary local variables

Defining a non-unique variable can still be done, using the normal syntax:

  .macro foo(b)
  .local int b
  .macro_local int $b
  .endm

When invoking the macro C<foo> as follows:

  .foo("x")

there will be two variables: C<b> and C<x>. When the macro is invoked twice:

  .sub main
    .foo("x")
    .foo("y")
  .end

the resulting code that is given to the parser will read as follows:

  .sub main
    .local int b
    .local int local__foo__x
    .local int b
    .local int local__foo__y
  .end

Obviously, this will result in an error, as the variable C<b> is defined
twice.  If you intend the macro to create unique variables names, use
C<.macro_local> instead of C<.local> to take advantage of the name munging.

=head1 EXAMPLES

=head2 Subroutine Definition

  .sub _sub_label [<subflag>]*
   .param int a
   .param int b
   .param int c
  ...
  .begin_return
   .return xy
  .end_return
  ...
  .end

=head2 Subroutine Call

  .const .Sub $P0 = "_sub_label"
  $P1 = new 'Continuation'
  set_addr $P1, ret_addr
  ...
  .local int x
  .local num y
  .local str z
  .begin_call
  .arg x
  .arg y
  .arg z
  .call $P0, $P1    # r = _sub_label(x, y, z)
  ret_addr:
  .local int r  # optional - new result var
  .result r
  .end_call

=head2 NCI Call

  load_lib $P0, "libname"
  dlfunc $P1, $P0, "funcname", "signature"
  ...
  .begin_call
  .arg x
  .arg y
  .arg z
  .nci_call $P1 # r = funcname(x, y, z)
  .local int r  # optional - new result var
  .result r
  .end_call

=head2 Subroutine Call Syntactic Sugar

  ...  # variable decls
  r = _sub_label(x, y, z)
  (r1[, r2 ...]) = _sub_label(x, y, z)
  _sub_label(x, y, z)

This also works for NCI calls, as the subroutine PMC will be
a NCI sub, and on invocation will do the Right Thing.
Instead of the label a subroutine object can be used too:

   find_global $P0, "_sub_label"
   $P0(args)


=head2 Methods

  .namespace [ "Foo" ]

  .sub _sub_label :method [,Subpragma, ...]
   .param int a
   .param int b
   .param int c
   ...
   self."_other_meth"()
  ...
  .begin_return
   .return xy
  .end_return
  ...
  .end

The variable "self" automatically refers to the invocating object, if the
subroutine declaration contains "method".

=head2 Calling Methods

The syntax is very similar to subroutine calls. The call is done with
C<meth_call> which must immediately be preceded by the C<.invocant>:

   .local pmc class
   .local pmc obj
   newclass class, "Foo"
   new obj, class
  .begin_call
  .arg x
  .arg y
  .arg z
  .invocant obj
  .meth_call "_method" [, $P1 ] # r = obj."_method"(x, y, z)
  .local int r  # optional - new result var
  .result r
  .end_call

The return continuation is optional. The method can be a string
constant or a string variable.

=head2 Returning and Yielding

  .return ( a, b )      # return the values of a and b

  .return ()            # return no value

  .return func_call()   # tail call function

  .return o."meth"()    # tail method call

Similarly, one can yield using the .yield directive

  .yield ( a, b )      # yield with the values of a and b

  .yield ()            # yield with no value


=head2 Stack calling conventions

Arguments are B<save>d in reverse order onto the user stack:

   .arg y   # save args in reversed order
   .arg x
   call _foo    #(r, s) = _foo(x,y)
   .local int r
   .local int s
   .result r    # restore results in order
   .result s    #

and return values are B<restore>d in argument order from there.



 .sub _foo      # sub foo(int a, int b)
   saveall
   .param int a         # receive arguments from left to right
   .param int b
   ...

   .return mi       # return (pl, mi), push results
   .return pl       # in reverse order
   restoreall
   ret
 .end

Pushing arguments in reversed order on the user stack makes the left
most argument the top of stack entry. This allows for a variable
number of function arguments (and return values), where the left most
argument before a variable number of following arguments is the
argument count.


=head1 ATTACHMENTS

N/A

=head1 FOOTNOTES

N/A

=head1 REFERENCES

See C<docs/imcc/macros.pod>

=cut

__END__
Local Variables:
  fill-column:78
End: