# $Id: antlr3.pod 18590 2007-05-19 13:31:13Z bernhard $

=head1 Overview

These are some ramblings on using ANTLR 3 for Plumhead, or with Parrot in general.

=head1 Parsing in general

=head1 ANTLR 3

See http://www.antlr.org/v3/index.html.

=head2 Running

Plumhead.java needs to find the needed classes. This works for me:

  export ANTLR_HOME=/home/bernhard/devel/ANTLR/antlr-3
  export PARROT_HOME=/home/bernhard/devel/Parrot/repos/parrot
  export CLASSPATH=$ANTLR_HOME/lib/antlr-2.7.7.jar:\
$ANTLR_HOME/lib/antlr-3.0.jar:\
$ANTLR_HOME:/lib/antlr-runtime-3.0.jar:\
$ANTLR_HOME/lib/stringtemplate-3.0.jar:\
$PARROT_HOME/languages/plumhead/src/antlr3:\
$PARROT_HOME/languages/plumhead 

And see the targets maintain-antlr3, build-antlr3, test-antlr3 in plumhead/Makefile.

=head2 Syntax

Lexer, Parser and TreeParser are in the same file, speak grammar.
C and C++ style comments are accepted.

'+' is one or many

'(  )' is for grouping
'|'    as for alternation 
"''"   Sring delimeter, honoring '\t', '\n', '\r'

'{   }' are actions
';'     delimits rules
'grammar <name>', set name of Parser, Name of autogenerated Lexer is generated from it

Tell to generate an AST and set lookahead
options 
{
    output=AST;
    ASTLabelType=CommonTree;
    k = 2;                            
}

'Sigil $' is for referencing alternations in actions, Lexer items only ???, also for setting returns

'->' Is for tree construction
'^^' Makes a mother
'^' Is for matching of tree nodes
'[]' declaration and passing of parameters

@members  declare additional member variables in the parser class

@init   ??

scope   a stack for symbols
 
{
  $channel = HIDDEN;
}
put match into Nirwana   
  

=head2 Lexer

The lexer specification can be in the parser specification.
A lexer grammar is automatically generated.
'protected' is gone.

=head2 Parser

=head2 TreeParser

=head2 StringTemplate

=head1 ANTLR Backends

=head2 Java

=head2 Python

=head2 Perl5

=head1 ANTLR and Parrot

=head2 Backend for Parrot

=head2 Plumhead

=head1 Glossary

=head1 AUTHOR

Bernhard Schmalhofer - <Bernhard.Schmalhofer@gmx.de>

=head1 SEE ALSO

  L<http://www.antlr.org/>
  L<http://www.antlr.org/v3/index.html>
  L<http://www.antlr.org/wiki/display/ANTLR3/Welcome+to+ANTLR+V3>
  L<http://www.antlr.org:8080/pipermail/antlr-dev/>

=cut