# Copyright: 2001-2005 The Perl Foundation.  All Rights Reserved.
# $Id: syntax.pod 7851 2005-04-16 11:06:03Z leo $

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

=item charset:encoding:"string constant"

Like above with an extra encoding attached to the string.
Currently unimplemented.

=item 'char constant'

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

=item numeric constants

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

=back

=head2 Directive instructions

=over 4

=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 .endnamespace <identifier>

Defines the range of a namespace. Local variables inside a namespace
are mangled as <namespaceidentifier::varidentifier>.

=item .param <type> <identifier>

Like B<.local> and generates PASM B<restore identifier>.

=item .param <reg>

=item .result <var>

B<restore> from stack.

=item .arg <var>

=item .return <var>

B<save> on stack.

=item .pcc_*

Directives used for Parrot Calling Conventions.

=back

=head2 Instructions

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

=over 4

=item call <identifier>

B<bsr> <identifier>.

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