=head1 NAME

IMCC - parsing

=head1 VERSION

=over 4

=item 0.1 initial

=item 0.2 lexicals

=item 0.3 pod markers

=item 0.4 deprecate nested subs and code outside compilation units

=back

=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

Comment start with B<#> and end at line end.

=head2 POD

Everything enclosed in POD markers is ignored.

	=some_pod_marker in col 1
	...
	=cut

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

=head1 Compilation units

=head2 Subroutines .sub ... .end

	.sub _name
		statements
		...
	.end

defines a subroutine with the entry point B<_name>. Subroutine entry
points (as all global labels) have to start with an underscore. The
statements may contain valid PIR or PASM statements.

=head2 Subroutines .pcc_sub ... .end

	.pcc_sub _name
		statements
		...
	.end

Like above with parrot calling conventions.
Subroutines according to Parrot Calling Conventions (PCC) are
described in F<docs/calling_conventions.pod>.

=head2 Assembly blocks .emit ... .eom

	.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

Anything outside compilation units will be ignored in the near future.

=head2 Nested subs

Nested subroutines are deprecated and will be removed as well.

=head1 Symbols, constants and labels

I<Compilation units> maintain their own symbol table containing local
labels and variable symbols. This symbol table I<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
I<ghash>.

This allows for global constant folding beyond subroutine scope.

Local labels in different I<compilation units> with the same name are
allowed, though assembling the generated PASM
doesn't work. Running this code inside imcc is ok.
This will probably change 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/syn/sub.t>, F<t/imcpasm/sub.t>,
F<t/syn/scope.t>

=head1 AUTHOR

Leopold Toetsch <lt@toetsch.at>
