# Copyright: 2001-2005 The Perl Foundation.  All Rights Reserved.
# $Id: parsing.pod 7546 2005-02-20 19:25:37Z bernhard $

=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

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>. Subroutine entry
points have to start with an underscore (as do all other global 
labels). The statements in the subroutine must be valid PIR or PASM.

=head2 Subroutines: .pcc_sub ... .end

	.sub name
		statements
		...
	.end

As above, but 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 deprecated and will be removed in the near
future.

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

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/syn/sub.t>, F<t/imcpasm/sub.t>,
F<t/syn/scope.t>

=head1 AUTHOR

Leopold Toetsch <lt@toetsch.at>
