# Copyright: 2001-2005 The Perl Foundation.  All Rights Reserved.
# $Id: syntax.pod 8385 2005-06-15 20:49:11Z chip $

=head1 NAME

IMCC - syntax

=head1 VERSION

=over 4

=item 0.1 initial

=back

=head1 OVERVIEW

This document describes the IMCC syntax.

=head1 DESCRIPTION

=head1 Comments and empty lines

Comments start with B<#> and last until the following newline. These
and empty lines are ignored.

=head1 Statements

A valid imcc program consists of a sequence of I<statements>. A
I<statement> is terminated by a newline (<NL>).

=head2 General statement format

  [label:] [instruction] <NL>

=head2 Labels

Optional label for the given instruction, can stand on its own line.
Global labels start with an underscore, local labels shouldn't. A label must
conform to the syntax of B<identifier> described below.

=head1 INSTRUCTIONS

=head2 Terms used here

=over 4

=item <identifier>

Start with a letter or underscore, then may contain additionally
digits and B<::>.

Example:

    a
    _a
    A42
    a::b_c

=item <type>

B<int>, B<float>, B<string>, B<pmc> or a valid parrot PMC type like
B<PerlArray>.

=item <reg>

A PASM register I0..I31, S0..S31, N0..N31, P0..P31, or a IMCC temporary
register $In, $Sn, $Nn, $Pn, where B<n> consists of digit(s) only.
The parrot register B<P31> is reserved for spilling and should not be
used in complex code sections, which might need spilling (see
F<operation.pod>).

=item <var>

A local B<identifier> or a B<reg> or a constant (when allowed).

=back

=head2 Constants

=over 4

=item "string constants"

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

=item charset:"string constant"

Like above with a chracter 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>.

=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, \\

=item encoding:charset:"string constant"

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

  set S0, utf8:unicode:"«"

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

=item 'char constant'

Are delimited by B<'>. They are taken to be C<ascii> encoded. No escape
sequences are processed.

=item numeric constants

B<0x> and B<0b> denote hex and binary constants.

=back

=head2 Directive instructions

=over 4

=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 B<n_>
prefix.

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


=item .HLL "hll_name", "hll_lib"

Define the HLL for the current module. If the string C<hll_lib> isn't empty
this B<compile time pragma> also loads the shared lib for the HLL, so that
integer types are working for creatin new PMCs.

=item .sub <identifier>

=item .end

Define a I<compilation unit> with the label B<identifier:>.

=item .emit

=item .eom

Define a I<compilation unit> containing PASM code.

=item .local <type> <identifier>

=item .sym <type> <identifier>

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

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

Define a named constant of style I<type> and value I<const>.

=item .namespace [ <identifier> ]

=item .namespace [ <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 with a C<\0>
prefix in the outer namespace's global pad.

=item .pcc_*

Directives used for Parrot Calling Conventions.

=back

=head2 Deprecated directives for subroutine parameters and return

=over 4

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

At the top of a subroutine, declare a local variable, in the mannter
of B<.local>, into which parameter(s) of the current subroutine should
be stored.  Available flags, not yet implemented in the old calling
convention: C<:slurpy> and C<:optional>.  [XXX Chip - finish this
update]

=item .param <reg> [:<flag> ...]

At the top of a subroutine, specify where parameter(s) of the current
subroutine should be stored.  Available flags, not yet implemented in
the old calling convention: C<:slurpy> and C<:optional>.  [XXX Chip -
finish this update]

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

Between B<.pcc_begin_return> and B<.pcc_end_return>, specify one or
more of the return value(s) of the current subroutine.  Available
flags: C<:flat>.  [XXX Chip - finish this update]

=back

=head2 Deprecated directives for making a PCC call

=over 4

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

Between B<.pcc_begin> and B<.pcc_call>, specify an argument to be
passed.  Available flags: C<:flat>.  [XXX Chip - finish this update]

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

Between B<.pcc_call> and B<.pcc_end>, specify where one or more return
value(s) should be stored.  Available flags, not yet implemented in
the old calling convention: C<:slurpy> and C<:optional>.  [XXX Chip -
finish this update]

=back

=head2 Instructions

Instructions may be a valid PASM instruction or anything listed here
below:

=over 4

=item goto <identifier>

B<branch> <identifier>.

=item if <var> goto <identifier>

=item unless <var> goto <identifier>

Translate to B<if x, identifier> or B<unless ..>.

=item if <var> <relop> <var> goto <identifier>

The B<relop> B<<, <=, ==, != E<gt>= E<gt>> translate to the PASM opcodes
B<lt>, B<le>, B<eq>, B<ne>, B<ge> or B<gt> B<var>, B<var>,
B<identifier>.

=item unless <var> <relop> <var> goto <identifier>

Like above, but branch if condition isn't met.

=item <var> = <var>

B<set var, var>

=item <var> = <unary> <var>

The B<unary>s B<!>, B<-> and B<~> generate B<not>, B<neg> and B<bnot> ops.

=item <var> = <var> <binary> <var>

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

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

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

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

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

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

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

A keyed B<set> operation or the assign B<substr> op with a length of
1.

=item <var> = new <type>

B<new var, .type>

=item <var> = new <type>, <var>

B<new var, .type, var>

=item <var> = defined <var>

B<defined var, var>

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

B<defined var, var[var]> the keyed op.

=item global "string" = <var>

B<store_global "string", var>

=item <var> = global "string"

B<find_global var, "string">

=item <var> = clone <var>

B<clone var, var>

=item <var> = addr <var>

B<set_addr var, var>

=back

=head1 SEE ALSO

F<parsing.pod>, F<calling_conventions.pod>

=head1 FILES

F<imcc.l>, F<imcc.y>

=head1 AUTHOR

Leopold Toetsch <lt@toetsch.at>
