# $Id: /mirror/trunk/languages/pipp/docs/antlr3.pod 28985 2008-07-02T14:45:33.271365Z bernhard  $

=head1 Overview

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

=head1 Making it work

Pipp.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/trunk
  export CLASSPATH=$ANTLR_HOME/lib/antlr-2.7.7.jar:\
$ANTLR_HOME/lib/antlr-3.0.1.jar:\
$ANTLR_HOME:/lib/antlr-runtime-3.0.1.jar:\
$ANTLR_HOME/lib/stringtemplate-3.1b1.jar:\
$PARROT_HOME/languages/pipp/src/antlr3:\
$PARROT_HOME/languages/pipp 

Now try:
   cd languages/pipp
   make maintain-antlr3
   make build-antlr3
   make test-antlr3 

=head1 ANTLR 3 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 Pipp

=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
