compilers/tge/TGE.pir

   1 # Copyright (C) 2005-2008, The Perl Foundation.
   2
   3 =head1 NAME
   4
   5 TGE - A tree grammar engine.
   6
   7 =head1 SYNOPSIS
   8
   9     # define a grammar leaf.tg
  10     transform min (Leaf) :language('PIR') {
  11         $P1 = getattribute node, "value"
  12         .return ($P1)
  13     }
  14     ...
  15     # and elsewhere...
  16
  17     .sub _main :main
  18         load_bytecode 'TGE.pir'
  19
  20         # Compile a grammar from the source grammar file
  21         .local pmc compiler
  22         compiler = new 'TGE::Compiler'
  23
  24         .local pmc grammar
  25         grammar = compiler.'compile'(source)
  26
  27         .local pmc tree
  28         # ... the tree to be manipulated
  29
  30         # Apply the grammar to the tree
  31         .local pmc TGI
  32         TGI = grammar.apply(tree)
  33
  34         # Return the result of a particular rule on a particular tree
  35         .local pmc result
  36         result = TGI.get('min')
  37         # ...
  38     .end
  39
  40 =head1 DESCRIPTION
  41
  42 TGE is a tool for transforming trees. Think of it as a good
  43 old-fashioned substitution, but instead of taking and returning strings,
  44 it takes and returns trees.
  45
  46 TGE is most heavily used in the compiler tools suite, where it
  47 transforms the trees output by PGE into abstract syntax trees.
  48
  49 TGE has both a procedural interface and a syntax interface. The syntax
  50 interface is easiest for humans to use when constructing grammars by
  51 hand. The procedural interface is preferable for computer generated
  52 grammars.
  53
  54 This is the syntax for tree grammar rules:
  55
  56     transform name (pattern) {
  57         # action
  58     }
  59
  60 The I<name> is the name of the transform rule. The I<pattern> is the type of
  61 node this particular transform applies to. You can have multiple transforms
  62 with the same name, as long as they match different patterns. The I<action> is
  63 a block of code that executes the transform. You can specify what language the
  64 action code is written in with the C<:language> modifier. At the moment, the
  65 only valid language is PIR. Within the block, two parameters are supplied for
  66 you: C<node> is the current node considered, and C<tree> is the top-level node
  67 for the entire tree.
  68
  69 The C<:applyto> modifier says which node the transform applies to.
  70
  71     transform name (pattern) :applyto('childname') {
  72         # action
  73     }
  74
  75 By default the transform applies to the current node (generally synthesized
  76 attributes), but you can specify the name of a child node if the transform
  77 applies to a child of the current node (generally inherited attributes).
  78
  79 =cut
  80
  81 .namespace [ 'TGE' ]
  82
  83 .sub '__onload' :load
  84     # make sure we execute this sub only once
  85     $P0 = get_global '$!tge_loaded'
  86     unless null $P0 goto end
  87     $P0 = new 'Integer'
  88     assign $P0, 1
  89     set_global '$!tge_loaded', $P0
  90
  91     # use other modules
  92     load_bytecode 'PGE.pbc'
  93     load_bytecode 'PGE/Util.pbc'
  94     load_bytecode 'compilers/tge/TGE/Rule.pbc'
  95     load_bytecode 'compilers/tge/TGE/Tree.pbc'
  96     load_bytecode 'compilers/tge/TGE/Parser.pbc'
  97     load_bytecode 'compilers/tge/TGE/Grammar.pbc'
  98     load_bytecode 'compilers/tge/TGE/Compiler.pbc'
  99
 100     # import <die> and <line_number> rules from PGE::Util
 101     $P0 = get_class ['TGE::Parser']
 102     $P1 = get_hll_global ['PGE::Util'], 'die'
 103     $P0.'add_method'('die', $P1)
 104     $P1 = get_hll_global ['PGE::Util'], 'line_number'
 105     $P0.'add_method'('line_number', $P1)
 106
 107   end:
 108     .return ()
 109 .end
 110
 111
 112
 113 =head1 AUTHOR
 114
 115 Allison Randal <allison@perl.org>
 116
 117 =cut
 118
 119 # Local Variables:
 120 #   mode: pir
 121 #   fill-column: 100
 122 # End:
 123 # vim: expandtab shiftwidth=4 ft=pir: