# Copyright (C) 2001-2005, The Perl Foundation.
# $Id: parsing.pod 12839 2006-05-30 14:34:31Z coke $

=head1 NAME

IMCC - parsing

=head1 OVERVIEW

This document describes the basic parsing functionality of IMCC.

=head1 DESCRIPTION

IMCC parses and generates code in terms of I<compilation units>. These
are self-contained blocks of code very similar to subroutines.

Code for a compilation unit is created as soon (or not earlier) as the
end of the unit is reached.

=head1 General imcc syntax

	program: subs

	subs: statements ...

=head2 Comments

Comments start with C<#>, which may appear at any point on a line, and end at 
the end of the line. 

=head2 POD sections

Everything enclosed in POD markers is ignored.

	=some_pod_marker in col 1
	...
	=cut

A POD section starts with a B<=> in column 1 and ends with a B<=cut> on a line
on its own.

=head1 Compilation units

=head2 Subroutines: .sub ... .end

This code:

	.sub name
		statements
		...
	.end


Defines a subroutine with the entry point C<_name>, 
using the Parrot calling conventions. See
F<docs/calling_conventions.pod> for more details.

=head2 Assembly blocks .emit ... .eom

This code:

	.emit
	_sub1:
		pasm_statements
		...
		ret
	...
	.eom

defines a compilation unit containing PASM statements only. Typical
usage is for language initialization and builtins code.

=head2 Code outside compilation units

Any code appearing outside of a compilation unit will be ignored 
(if not now, then in the near future).

=head2 Nested subs

Nested subroutines are not supported.

=head1 Symbols, constants and labels

I<Compilation units> maintain their own symbol table containing local
labels and variable symbols. This symbol table, C<hash>, is not visible
to code in different units.

If you need global variables, please use the B<global> opcode.

Global labels and constants are kept in the global symbol table
C<ghash>. This allows for global constant folding beyond the scope
of individual subroutines.

This also means that you currently can't use the same global symbol (e.g. 
subroutine name) in different namespaces. The following creates invalid code:

  .sub main
     ...
  .end

   .namespace ["main"]
  .sub main
     ...
  .end

Local labels in different I<compilation units> with the same name are
allowed, though assembling the generated PASM doesn't work. However,
running this code inside imcc is ok. This will probably change in the 
future so that local labels are mangled to be unique.

=head1 SEE ALSO

F<docs/calling_conventions.pod>

=head1 FILES

F<imcc.y>, F<instructions.c>, F<t/compilers/imcc/syn/sub.t>,
F<t/compilers/imcc/imcpasm/sub.t>, F<t/compilers/imcc/syn/scope.t>

=head1 AUTHOR

Leopold Toetsch <lt@toetsch.at>

=cut