[svn:parrot-pdd] r26738 - trunk/docs/pdds/draft

Author: kjs
Date: Fri Apr  4 01:50:45 2008
New Revision: 26738

Modified:
   trunk/docs/pdds/draft/pdd29_compiler_tools.pod

Log:
[pdd29] add more stuff to pdd29

Modified: trunk/docs/pdds/draft/pdd29_compiler_tools.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd29_compiler_tools.pod	(original)
+++ trunk/docs/pdds/draft/pdd29_compiler_tools.pod	Fri Apr  4 01:50:45 2008
@@ -14,6 +14,17 @@
 Will "Coke" Coleda
 Klaas-Jan Stol
 
+=head1 DEFINITIONS
+
+=head2 Compiler
+
+In this document, when we speak of a I<compiler>, we mean
+PCT-based compilers.
+
+=head2 HLL
+
+A High-Level Language. Examples are: Perl, Ruby, Python, Lua, Tcl, etc.
+
 =head1 ABSTRACT
 
 This PDD specifies the Parrot Compiler Tools (PCT).
@@ -45,15 +56,70 @@
 get started with the PCT.
 The script is located in C<tools/dev/mk_language_shell.pl>.
 
-{{ Not sure whether the mk_language_shell.pl script should be mentioned long
-term }}
+{{ Not sure whether the mk_language_shell.pl script should be mentioned long term
+   In a sense, this script can also be considered part of the parrot compiler "tools",
+   as it is used to create a compiler.
+}}
+
+=head2 Parser Synopsis
+
+ grammar Foo is PCT::Grammar;
+
+ rule TOP {
+     <statement>*
+     {*}
+ }
+
+ rule statement {
+     <ident> '=' <expression>
+     {*}
+ }
+
+ rule expression is optable { ... }
+
+ proto infix:<+> is precedence('1') is pirop('n_add') { ... }
+
+ rule 'term:' is tighter(infix:<+>) is parsed(&term) { ... }
+
+ rule term {
+     | <ident> {*}       #= ident
+     | <number> {*}      #= number
+ }
+
+=head2 Actions Synopsis
+
+{{ Is this a good idea? }}
+
+class Foo::Grammar::Actions;
+
+ method TOP($/) {
+     my $past := PAST::Block.new( :blocktype('declaration') );
+     for $<statement> {
+         $past.push( $( $_ ) );
+     }
+     make $past;
+ }
 
+ method statement($/) {
+     ...
+ }
+
+ method expression($/, $key) {
+     ...
+ }
+
+ method term($/, $key) {
+     make $( $/{$key} );
+ }
+
+=head2 Running the compiler
 
 Running the compiler is then done as follows:
 
  $ parrot foo.pbc [--target=[parse|past|post|pir]] <file>
 
-{{ other options? }}
+{{ other options? Maybe --target=pbc in the future, once PBC can be
+   generated? }}
 
 =head1 DESCRIPTION
 
@@ -70,7 +136,7 @@
 
 =item * create an intermediate data structure (Abstract Syntax Tree)
 
-=item * generate executable code (Parrot Intermediate Representation)
+=item * generate executable Parrot code
 
 =back
 
@@ -127,19 +193,45 @@
 
 =head3 Source to Parse Tree
 
-{{ XXX }}
+The first stage of a PCT-based compiler is done by the C<parser>. The
+parser is defined as a set of Perl 6 Rules, which is processed by the
+Perl 6 Rules compiler. This results in a generated PIR file that
+implements the parser.
+
+{{ Doesn't this make the Perl 6 rules compiler part of the PCT? }}
+
+During the first stage, the source (input string) is parsed, resulting
+in a C<parse tree>.
 
 =head3 Parse tree to PAST
 
-{{ XXX }}
+The second stage converts the parse tree into a Parrot Abstract Syntax Tree
+(PAST). PAST is a data structure consisting of PAST nodes, each of which
+represents a common HLL construct. While all languages differ in syntax,
+many constructs in different HLLs map to the same semantics. This second
+transformation is executed during the parse stage. The transformations
+of the parse tree nodes into PAST nodes is done by so-called parse actions,
+which are methods of a class that is specified through the C<parseactions>
+attribute of the HLLCompiler. Such classes are implemented in NQP.
+
+{{ How do we say that this is not obligatory; you could also use PIR,
+   and in the future maybe other languages.
+}}
 
 =head3 PAST to POST
 
-{{ XXX }}
+The third transformation converts the PAST into a Parrot Opcode Syntax Tree
+(POST). PAST nodes represent HLL constructs, which are transformed into a
+set of low-level POST nodes. A POST node is a low-level node, representing
+a single instruction, label, or a subroutine. While a PAST is very close to
+a HLL program, a POST is much closer to PIR code.
 
 =head3 POST to PIR
 
-{{ XXX }}
+The last transformation generates PIR code from the POST.
+
+The generated PIR is then fed into the Parrot executable, and processed
+into Parrot Byte Code (PBC) by the PIR compiler.
 
 =head2 Parrot Grammar Engine
 
@@ -147,6 +239,28 @@
 expressions. Besides I<classic> regular expressions, it also understands
 Perl 6 Rules. Such rules are special regular expressions to define a grammar.
 
+=head2 Parrot Abstract Syntax Tree
+
+The PCT includes a set of PAST classes. PAST classes represent common language
+constructs, such as a C<while statement>.
+These are described extensively in L<docs/pdds/pdd26_ast.pod>.
+
+=head2 Parrot Opcode Syntax Tree
+
+=head3 POST::Node
+
+POST::Node is the base class for all other POST classes.
+
+=head3 POST::Op
+
+=head3 POST::Ops
+
+=head3 POST::Label
+
+=head3 POST::Sub
+
+
+
 =head2 PCT::Grammar
 
 The class C<PCT::Grammar> is a built-in grammar class that can be used as
@@ -169,7 +283,8 @@
 =head2 PCT::HLLCompiler
 
 All PCT-based compilers use a HLLCompiler object as a compiler driver.
-This object invokes the different compiler phases.
+It acts as a I<facade> for the compiler. This object invokes the different
+compiler phases.
 
 =head3 HLLCompiler API Methods
 

• [svn:parrot-pdd] r26738 - trunk/docs/pdds/draft by kjs