pt(3)



pt(3tcl)                         Parser Tools                         pt(3tcl)

______________________________________________________________________________

NAME
       pt - Parser Tools Application

SYNOPSIS
       package require Tcl  8.5

       pt generate resultformat ?options...? resultfile inputformat inputfile

______________________________________________________________________________

DESCRIPTION
       Are  you  lost ?  Do you have trouble understanding this document ?  In
       that case please read the overview  provided  by  the  Introduction  to
       Parser  Tools.  This document is the entrypoint to the whole system the
       current package is a part of.

       This document describes pt, the  main  application  of  the  module,  a
       parser generator. Its intended audience are people who wish to create a
       parser for some language of theirs. Should you wish to modify  the  ap-
       plication  instead,  please see the section about the application's In-
       ternals for the basic references.

       It resides in the User Application Layer of Parser Tools.

       IMAGE: arch_user_app

COMMAND LINE
       pt generate resultformat ?options...? resultfile inputformat inputfile
              This sub-command of the application reads the parsing expression
              grammar  stored in the inputfile in the format inputformat, con-
              verts it to the resultformat under the direction of the (format-
              specific)  set  of  options specified by the user and stores the
              result in the resultfile.

              The inputfile has to exist, while the resultfile may be created,
              overwriting  any  pre-existing  content of the file. Any missing
              directory in the path to the resultfile will be created as well.

              The exact form of the result for, and the set  of  options  sup-
              ported  by the known result-formats, are explained in the upcom-
              ing sections of this document, with the list below providing  an
              index mapping between format name and its associated section. In
              alphabetical order:

              c      A resultformat. See section C Parser.

              container
                     A resultformat. See section Grammar Container.

              critcl A resultformat. See section C Parser Embedded In Tcl.

              json   A input- and resultformat. See section JSON  Grammar  Ex-
                     change.

              oo     A resultformat. See section TclOO Parser.

              peg    A  input- and resultformat. See section PEG Specification
                     Language.

              snit   A resultformat. See section Snit Parser.

       Of the seven possible results four are parsers outright (c, critcl, oo,
       and  snit), one (container) provides code which can be used in conjunc-
       tion with a generic parser (also known as a grammar  interpreter),  and
       the last two (json and peg) are doing double-duty as input formats, al-
       lowing the transformation of grammars for exchange,  reformatting,  and
       the like.

       The created parsers fall into three categories:

       .nf  + --- C ---> critcl, c | + --- specialized -+ |                  |
       ---+                  + --- Tcl -> snit, oo | + ---  interpreted  (Tcl)
       ------> container .fi

       Specialized parsers implemented in C
              The  fastest parsers are created when using the result formats c
              and critcl. The first returns the raw C  code  for  the  parser,
              while the latter wraps it into a Tcl package using CriTcl.

              This makes the latter much easier to use than the former. On the
              other hand, the former can be adapted to the users' requirements
              through  a  multitude of options, allowing for things like usage
              of the parser outside of a Tcl environment, something the critcl
              format  doesn't  support. As such the c format is meant for more
              advanced users, or users with special needs.

              A disadvantage of all the parsers in this section is the need to
              run  them through a C compiler to make them actually executable.
              This is not something everyone has the necessary tools for.  The
              parsers  in  the next section are for people under such restric-
              tions.

       Specialized parsers implemented in Tcl
              As the parsers in this section are implemented in Tcl  they  are
              quite  a  bit slower than anything from the previous section. On
              the other hand this allows them to be used in pure-Tcl  environ-
              ments,  or in environments which allow only a limited set of bi-
              nary packages. In the latter case it  will  be  advantageous  to
              lobby  for  the  inclusion of the C-based runtime support (notes
              below) into the environment to reduce the impact of Tcl's on the
              speed of these parsers.

              The  relevant  formats  are snit and oo. Both place their result
              into a Tcl package containing a snit::type, or TclOO  class  re-
              spectively.

              Of  the  supporting  runtime,  which is the package pt::rde, the
              user has to know nothing but that it does  exist  and  that  the
              parsers  are  dependent  on it. Knowledge of the API exported by
              the runtime for the parsers' consumption is not required by  the
              parsers' users.

       Interpreted parsing implemented in Tcl
              The  last  category,  grammar interpretation. This means that an
              interpreter for parsing expression grammars takes  the  descrip-
              tion  of  the  grammar to parse input for, and uses it guide the
              parsing process.  This is the slowest of the available  options,
              as the interpreter has to continually run through the configured
              grammar, whereas the specialized parsers of  the  previous  sec-
              tions  have  the relevant knowledge about the grammar baked into
              them.

              The only places where using interpretation make sense  is  where
              the  grammar  for some input may be changed interactively by the
              user, as the interpretation allows for  quick  turnaround  after
              each change, whereas the previous methods require the generation
              of a whole new parser, which is not as fast.  On the other hand,
              wherever  the  grammar to use is fixed, the previous methods are
              much more advantageous as the time to generate the parser is mi-
              nuscule compared to the time the parser code is in use.

              The relevant result format is container.  It (quickly) generates
              grammar descriptions (instead of a full parser) which match  the
              API expected by ParserTools' grammar interpreter.  The latter is
              provided by the package pt::peg::interp.

       All the parsers generated by critcl, snit, and oo, and the grammar  in-
       terpreter share a common API for access to the actual parsing function-
       ality, making them all plug-compatible.  It is described in the  Parser
       API specification document.

PEG SPECIFICATION LANGUAGE
       peg, a language for the specification of parsing expression grammars is
       meant to be human readable, and writable as well, yet strict enough  to
       allow its processing by machine. Like any computer language. It was de-
       fined to make writing the specification of a  grammar  easy,  something
       the other formats found in the Parser Tools do not lend themselves too.

       For  either  an introduction to or the formal specification of the lan-
       guage, please go and read the PEG Language Tutorial.

       When used as a result-format this format  supports  the  following  op-
       tions:

       -file string
              The value of this option is the name of the file or other entity
              from which the grammar came, for which the command is  run.  The
              default value is unknown.

       -name string
              The  value of this option is the name of the grammar we are pro-
              cessing.  The default value is a_pe_grammar.

       -user string
              The value of this option is the name of the user for  which  the
              command is run. The default value is unknown.

       -template string
              The  value of this option is a string into which to put the gen-
              erated text and the values of the other options. The various lo-
              cations  for  user-data  are  expected  to be specified with the
              placeholders listed below. The default value is "@code@".

              @user@ To be replaced with the value of the option -user.

              @format@
                     To be replaced with the the constant PEG.

              @file@ To be replaced with the value of the option -file.

              @name@ To be replaced with the value of the option -name.

              @code@ To be replaced with the generated text.

JSON GRAMMAR EXCHANGE
       The json format for parsing expression grammars was written as  a  data
       exchange  format not bound to Tcl. It was defined to allow the exchange
       of grammars with PackRat/PEG based parser  generators  for  other  lan-
       guages.

       For  the  formal  specification  of  the  JSON grammar exchange format,
       please go and read The JSON Grammar Exchange Format.

       When used as a result-format this format  supports  the  following  op-
       tions:

       -file string
              The value of this option is the name of the file or other entity
              from which the grammar came, for which the command is  run.  The
              default value is unknown.

       -name string
              The  value of this option is the name of the grammar we are pro-
              cessing.  The default value is a_pe_grammar.

       -user string
              The value of this option is the name of the user for  which  the
              command is run. The default value is unknown.

       -indented boolean
              If  this  option is set the system will break the generated JSON
              across lines and indent it according  to  its  inner  structure,
              with each key of a dictionary on a separate line.

              If  the  option  is not set (the default), the whole JSON object
              will be written on a single line, with minimum  spacing  between
              all elements.

       -aligned boolean
              If this option is set the system will ensure that the values for
              the keys in a dictionary are vertically aligned with each other,
              for  a  nice  table effect.  To make this work this also implies
              that -indented is set.

              If the option is not set (the default), the output is  formatted
              as per the value of indented, without trying to align the values
              for dictionary keys.

C PARSER EMBEDDED IN TCL
       The critcl format is executable code, a parser for the grammar. It is a
       Tcl  package with the actual parser implementation written in C and em-
       bedded in Tcl via the critcl package.

       This result-format supports the following options:

       -file string
              The value of this option is the name of the file or other entity
              from  which  the grammar came, for which the command is run. The
              default value is unknown.

       -name string
              The value of this option is the name of the grammar we are  pro-
              cessing.  The default value is a_pe_grammar.

       -user string
              The  value  of this option is the name of the user for which the
              command is run. The default value is unknown.

       -class string
              The value of this option is the name of the class  to  generate,
              without leading colons.  The default value is CLASS.

              For a simple value X without colons, like CLASS, the parser com-
              mand will be X::X. Whereas  for  a  namespaced  value  X::Y  the
              parser command will be X::Y.

       -package string
              The value of this option is the name of the package to generate.
              The default value is PACKAGE.

       -version string
              The value of this option is the version of the package to gener-
              ate.  The default value is 1.

C PARSER
       The  c  format is executable code, a parser for the grammar. The parser
       implementation is written in C and can be tweaked to the  users'  needs
       through a multitude of options.

       The  critcl  format, for example, is implemented as a canned configura-
       tion of these options on top of the generator for c.

       This result-format supports the following options:

       -file string
              The value of this option is the name of the file or other entity
              from  which  the grammar came, for which the command is run. The
              default value is unknown.

       -name string
              The value of this option is the name of the grammar we are  pro-
              cessing.  The default value is a_pe_grammar.

       -user string
              The  value  of this option is the name of the user for which the
              command is run. The default value is unknown.

       -template string
              The value of this option is a string into which to put the  gen-
              erated  text  and  the other configuration settings. The various
              locations for user-data are expected to be  specified  with  the
              placeholders listed below. The default value is "@code@".

              @user@ To be replaced with the value of the option -user.

              @format@
                     To be replaced with the the constant C/PARAM.

              @file@ To be replaced with the value of the option -file.

              @name@ To be replaced with the value of the option -name.

              @code@ To be replaced with the generated Tcl code.

              The  following  options  are  special,  in  that they will occur
              within the generated code, and are replaced there as well.

              @statedecl@
                     To be replaced with the value of the option state-decl.

              @stateref@
                     To be replaced with the value of the option state-ref.

              @strings@
                     To be replaced with the value of the  option  string-var-
                     name.

              @self@ To be replaced with the value of the option self-command.

              @def@  To  be  replaced  with the value of the option fun-quali-
                     fier.

              @ns@   To be replaced with the value of the option namespace.

              @main@ To be replaced with the value of the option main.

              @prelude@
                     To be replaced with the value of the option prelude.

       -state-decl string
              A C string representing the argument declaration to use  in  the
              generated  parsing  functions  to refer to the parsing state. In
              essence type and argument name.  The default value is the string
              RDE_PARAM p.

       -state-ref string
              A C string representing the argument named used in the generated
              parsing functions to refer to the parsing  state.   The  default
              value is the string p.

       -self-command string
              A  C string representing the reference needed to call the gener-
              ated parser function (methods ...) from another parser fonction,
              per  the  chosen framework (template).  The default value is the
              empty string.

       -fun-qualifier string
              A C string containing the attributes to give  to  the  generated
              functions  (methods  ...),  per the chosen framework (template).
              The default value is static.

       -namespace string
              The name of the C namespace the parser functions (methods,  ...)
              shall  reside  in,  or  a  general prefix to add to the function
              names.  The default value is the empty string.

       -main string
              The name of the main function (method, ...) to be called by  the
              chosen framework (template) to start parsing input.  The default
              value is __main.

       -string-varname string
              The name of the variable used for the table of strings  used  by
              the  generated  parser,  i.e. error messages, symbol names, etc.
              The default value is p_string.

       -prelude string
              A snippet of code to be inserted at the head of  each  generated
              parsing function.  The default value is the empty string.

       -indent integer
              The  number  of  characters to indent each line of the generated
              code by.  The default value is 0.

       -comments boolean
              A flag controlling the generation of  code  comments  containing
              the  original parsing expression a parsing function is for.  The
              default value is on.

SNIT PARSER
       The snit format is executable code, a parser for the grammar. It  is  a
       Tcl  package  holding  a  snit::type, i.e. a class, whose instances are
       parsers for the input grammar.

       This result-format supports the following options:

       -file string
              The value of this option is the name of the file or other entity
              from  which  the grammar came, for which the command is run. The
              default value is unknown.

       -name string
              The value of this option is the name of the grammar we are  pro-
              cessing.  The default value is a_pe_grammar.

       -user string
              The  value  of this option is the name of the user for which the
              command is run. The default value is unknown.

       -class string
              The value of this option is the name of the class  to  generate,
              without  leading colons. Note, it serves double-duty as the name
              of the package to generate too, if option -package is not speci-
              fied,  see  below.  The default value is CLASS, applying if nei-
              ther option -class nor -package were specified.

       -package string
              The value of this option is the name of the package to generate,
              without  leading colons. Note, it serves double-duty as the name
              of the class to generate too, if option -class is not specified,
              see  above.   The  default value is PACKAGE, applying if neither
              option -package nor -class were specified.

       -version string
              The value of this option is the version of the package to gener-
              ate.  The default value is 1.

TCLOO PARSER
       The oo format is executable code, a parser for the grammar. It is a Tcl
       package holding a TclOO class, whose instances are parsers for the  in-
       put grammar.

       This result-format supports the following options:

       -file string
              The value of this option is the name of the file or other entity
              from which the grammar came, for which the command is  run.  The
              default value is unknown.

       -name string
              The  value of this option is the name of the grammar we are pro-
              cessing.  The default value is a_pe_grammar.

       -user string
              The value of this option is the name of the user for  which  the
              command is run. The default value is unknown.

       -class string
              The  value  of this option is the name of the class to generate,
              without leading colons. Note, it serves double-duty as the  name
              of the package to generate too, if option -package is not speci-
              fied, see below.  The default value is CLASS, applying  if  nei-
              ther option -class nor -package were specified.

       -package string
              The value of this option is the name of the package to generate,
              without leading colons. Note, it serves double-duty as the  name
              of the class to generate too, if option -class is not specified,
              see above.  The default value is PACKAGE,  applying  if  neither
              option -package nor -class were specified.

       -version string
              The value of this option is the version of the package to gener-
              ate.  The default value is 1.

GRAMMAR CONTAINER
       The container format is another form of describing  parsing  expression
       grammars.  While  data in this format is executable it does not consti-
       tute a parser for the grammar. It always has to be used in  conjunction
       with the package pt::peg::interp, a grammar interpreter.

       The  format  represents grammars by a snit::type, i.e. class, whose in-
       stances are API-compatible to the instances of  the  pt::peg::container
       package, and which are preloaded with the grammar in question.

       This result-format supports the following options:

       -file string
              The value of this option is the name of the file or other entity
              from which the grammar came, for which the command is  run.  The
              default value is unknown.

       -name string
              The  value of this option is the name of the grammar we are pro-
              cessing.  The default value is a_pe_grammar.

       -user string
              The value of this option is the name of the user for  which  the
              command is run. The default value is unknown.

       -mode bulk|incremental
              The value of this option controls which methods of pt::peg::con-
              tainer instances are used to specify the grammar,  i.e.  preload
              it into the container. There are two legal values, as listed be-
              low. The default is bulk.

              bulk   In this mode the methods start, add, modes, and rules are
                     used  to  specify the grammar in a bulk manner, i.e. as a
                     set of nonterminal symbols, and two dictionaries  mapping
                     from  the symbols to their semantic modes and parsing ex-
                     pressions.

                     This mode is the default.

              incremental
                     In this mode the methods start, add, mode, and  rule  are
                     used to specify the grammar piecemal, with each nontermi-
                     nal having its own block of defining commands.

       -template string
              The value of this option is a string into which to put the  gen-
              erated  code  and  the other configuration settings. The various
              locations for user-data are expected to be  specified  with  the
              placeholders listed below. The default value is "@code@".

              @user@ To be replaced with the value of the option -user.

              @format@
                     To be replaced with the the constant CONTAINER.

              @file@ To be replaced with the value of the option -file.

              @name@ To be replaced with the value of the option -name.

              @mode@ To be replaced with the value of the option -mode.

              @code@ To be replaced with the generated code.

EXAMPLE
       In  this section we are working a complete example, starting with a PEG
       grammar and ending with running the parser generated from it over  some
       input, following the outline shown in the figure below:

       IMAGE: flow

       Our grammar, assumed to the stored in the file "calculator.peg" is

              PEG calculator (Expression)
                  Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
                  Sign       <- '-' / '+'                                     ;
                  Number     <- Sign? Digit+                                  ;
                  Expression <- Term (AddOp Term)*                            ;
                  MulOp      <- '*' / '/'                                     ;
                  Term       <- Factor (MulOp Factor)*                        ;
                  AddOp      <- '+'/'-'                                       ;
                  Factor     <- '(' Expression ')' / Number                   ;
              END;

       From this we create a snit-based parser via

              pt generate snit calculator.tcl -class calculator -name calculator peg calculator.peg

       which  leaves  us with the parser package and class written to the file
       "calculator.tcl".  Assuming that this  package  is  then  properly  in-
       stalled  in a place where Tcl can find it we can now use this class via
       a script like

                  package require calculator

                  lassign $argv input
                  set channel [open $input r]

                  set parser [calculator]
                  set ast [$parser parse $channel]
                  $parser destroy
                  close $channel

                  ... now process the returned abstract syntax tree ...

       where the abstract syntax tree stored in the variable will look like

              set ast {Expression 0 4
                  {Factor 0 4
                      {Term 0 2
                          {Number 0 2
                              {Digit 0 0}
                              {Digit 1 1}
                              {Digit 2 2}
                          }
                      }
                      {AddOp 3 3}
                      {Term 4 4
                          {Number 4 4
                              {Digit 4 4}
                          }
                      }
                  }
              }

       assuming that the input file and channel contained the text

               120+5
       A more graphical representation of the tree would be

       .nf +- Digit 0 0 | 1 |            | +- Term 0 2  ---  Number  0  2  -+-
       Digit   1   1   |   2   |                            |             |  |
       +- Digit 2 2 | 0 |                                        |  Expression
       0  4  ---  Factor  0  4 -+----------------------------- AddOp 3 3 | + |
       | +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 .fi

       Regardless, at this point it is the user's responsibility to work  with
       the tree to reach whatever goal she desires. I.e. analyze it, transform
       it, etc. The package pt::ast should be of help here, providing commands
       to walk such ASTs structures in various ways.

       One important thing to note is that the parsers used here return a data
       structure representing the structure of the input per the  grammar  un-
       derlying the parser. There are no callbacks during the parsing process,
       i.e. no parsing actions, as most other parsers will have.

       Going back to the last snippet of code, the execution of the parser for
       some  input,  note how the parser instance follows the specified Parser
       API.

INTERNALS
       This section is intended for users of the  application  which  wish  to
       modify or extend it. Users only interested in the generation of parsers
       can ignore it.

       The main functionality of the application is encapsulated in the  pack-
       age pt::pgen. Please read it for more information.

BUGS, IDEAS, FEEDBACK
       This  document,  and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category pt of  the
       Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please also
       report any ideas for enhancements  you  may  have  for  either  package
       and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the out-
       put of diff -u.

       Note further that  attachments  are  strongly  preferred  over  inlined
       patches.  Attachments  can  be  made  by  going to the Edit form of the
       ticket immediately after its creation, and  then  using  the  left-most
       button in the secondary navigation bar.

KEYWORDS
       EBNF,  LL(k),  PEG,  TDPL, context-free languages, expression, grammar,
       matching, parser, parsing expression, parsing expression grammar,  push
       down  automaton,  recursive descent, state, top-down parsing languages,
       transducer

CATEGORY
       Parsing and Grammars

COPYRIGHT
       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>

tcllib                                 1                              pt(3tcl)

Man(1) output converted with man2html
list of all man pages