"Fossies" - the Fresh Open Source Software Archive

Member "SAOImageDS9/tcllib/apps/pt.man" (13 Nov 2019, 8646 Bytes) of package /linux/misc/ds9.8.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 [comment {-*- text -*- doctools manpage}]
    2 [manpage_begin pt n 1]
    3 [include ../modules/pt/include/module.inc]
    4 [titledesc {Parser Tools Application}]
    5 [description]
    6 [include ../modules/pt/include/ref_intro.inc]
    7 
    8 This document describes [cmd pt], the main application of the module,
    9 a [term {parser generator}]. Its intended audience are people who wish
   10 to create a parser for some language of theirs. Should you wish to
   11 modify the application instead, please see the section about the
   12 application's [sectref {Internals}] for the basic references.
   13 
   14 [para]
   15 
   16 It resides in the User Application Layer of Parser Tools.
   17 [para][image arch_user_app][para]
   18 
   19 [section {Command Line}]
   20 
   21 [list_begin definitions]
   22 
   23 [call [cmd pt] [method generate] \
   24       [arg resultformat] [opt [arg options...]] [arg resultfile] \
   25       [arg inputformat] [arg inputfile]]
   26 
   27 This sub-command of the application reads the parsing expression
   28 grammar stored in the [arg inputfile] in the format [arg inputformat],
   29 converts it to the [arg resultformat] under the direction of the
   30 (format-specific) set of options specified by the user and stores the
   31 result in the [arg resultfile].
   32 
   33 [para]
   34 
   35 The [arg inputfile] has to exist, while the [arg resultfile] may be
   36 created, overwriting any pre-existing content of the file. Any missing
   37 directory in the path to the [arg resultfile] will be created as well.
   38 
   39 [para]
   40 
   41 The exact form of the result for, and the set of options supported by
   42 the known result-formats, are explained in the upcoming sections of
   43 this document, with the list below providing an index mapping between
   44 format name and its associated section. In alphabetical order:
   45 
   46 [para]
   47 [list_begin definitions]
   48 [def [const c]]         A [term resultformat]. See section [sectref {C Parser}].
   49 [def [const container]] A [term resultformat]. See section [sectref {Grammar Container}].
   50 [def [const critcl]]    A [term resultformat]. See section [sectref {C Parser Embedded In Tcl}].
   51 [def [const json]]      A [term input]- and [term resultformat]. See section [sectref {JSON Grammar Exchange}].
   52 [def [const oo]]        A [term resultformat]. See section [sectref {TclOO Parser}].
   53 [def [const peg]]       A [term input]- and [term resultformat]. See section [sectref {PEG Specification Language}].
   54 [def [const snit]]      A [term resultformat]. See section [sectref {Snit Parser}].
   55 [list_end]
   56 [list_end]
   57 
   58 Of the seven possible results four are parsers outright ([const c],
   59 [const critcl], [const oo], and [const snit]), one ([const container])
   60 provides code which can be used in conjunction with a generic parser
   61 (also known as a grammar interpreter), and the last two ([const json]
   62 and [const peg]) are doing double-duty as input formats, allowing the
   63 transformation of grammars for exchange, reformatting, and the like.
   64 
   65 [para]
   66 
   67 The created parsers fall into three categories:
   68 [include ../modules/pt/include/gen_options.inc]
   69 
   70 [list_begin definitions]
   71 
   72 [def [const {Specialized parsers implemented in C}]]
   73 
   74 The fastest parsers are created when using the result formats
   75 [const c] and [const critcl]. The first returns the raw C code for the
   76 parser, while the latter wraps it into a Tcl package using
   77 [term CriTcl].
   78 
   79 [para]
   80 
   81 This makes the latter much easier to use than the former. On the other
   82 hand, the former can be adapted to the users' requirements through a
   83 multitude of options, allowing for things like usage of the parser
   84 outside of a Tcl environment, something the [const critcl] format
   85 doesn't support. As such the [const c] format is meant for more
   86 advanced users, or users with special needs.
   87 
   88 [para]
   89 
   90 A disadvantage of all the parsers in this section is the need to run
   91 them through a C compiler to make them actually executable. This is
   92 not something everyone has the necessary tools for. The parsers in the
   93 next section are for people under such restrictions.
   94 
   95 [def [const {Specialized parsers implemented in Tcl}]]
   96 
   97 As the parsers in this section are implemented in Tcl they are quite a
   98 bit slower than anything from the previous section. On the other hand
   99 this allows them to be used in pure-Tcl environments, or in
  100 environments which allow only a limited set of binary packages. In the
  101 latter case it will be advantageous to lobby for the inclusion of the
  102 C-based runtime support (notes below) into the environment to reduce
  103 the impact of Tcl's on the speed of these parsers.
  104 
  105 [para]
  106 
  107 The relevant formats are [const snit] and [const oo]. Both place their
  108 result into a Tcl package containing a [cmd snit::type], or TclOO
  109 [cmd class] respectively.
  110 
  111 [para]
  112 
  113 Of the supporting runtime, which is the package [package pt::rde], the
  114 user has to know nothing but that it does exist and that the parsers
  115 are dependent on it. Knowledge of the API exported by the runtime for
  116 the parsers' consumption is [emph not] required by the parsers' users.
  117 
  118 [def [const {Interpreted parsing implemented in Tcl}]]
  119 
  120 The last category, grammar interpretation. This means that an
  121 interpreter for parsing expression grammars takes the description of
  122 the grammar to parse input for, and uses it guide the parsing process.
  123 
  124 This is the slowest of the available options, as the interpreter has
  125 to continually run through the configured grammar, whereas the
  126 specialized parsers of the previous sections have the relevant
  127 knowledge about the grammar baked into them.
  128 
  129 [para]
  130 
  131 The only places where using interpretation make sense is where the
  132 grammar for some input may be changed interactively by the user, as
  133 the interpretation allows for quick turnaround after each change,
  134 whereas the previous methods require the generation of a whole new
  135 parser, which is not as fast.
  136 
  137 On the other hand, wherever the grammar to use is fixed, the previous
  138 methods are much more advantageous as the time to generate the parser
  139 is minuscule compared to the time the parser code is in use.
  140 
  141 [para]
  142 
  143 The relevant result format is [const container].
  144 
  145 It (quickly) generates grammar descriptions (instead of a full parser)
  146 which match the API expected by ParserTools' grammar interpreter.
  147 
  148 The latter is provided by the package [package pt::peg::interp].
  149 
  150 [list_end]
  151 
  152 All the parsers generated by [const critcl], [const snit], and
  153 [const oo], and the grammar interpreter share a common API for access
  154 to the actual parsing functionality, making them all
  155 plug-compatible.
  156 
  157 It is described in the [manpage {Parser API}] specification document.
  158 
  159 [section {PEG Specification Language}]
  160 [include ../modules/pt/include/format/whatis_peg.inc]
  161 [para]
  162 
  163 For either an introduction to or the formal specification of the
  164 language, please go and read the [manpage {PEG Language Tutorial}].
  165 
  166 [para]
  167 
  168 When used as a result-format this format supports the following
  169 options:
  170 
  171 [include ../modules/pt/include/format/options_peg.inc]
  172 
  173 [section {JSON Grammar Exchange}]
  174 [include ../modules/pt/include/format/whatis_json.inc]
  175 [para]
  176 
  177 For the formal specification of the JSON grammar exchange format,
  178 please go and read [manpage {The JSON Grammar Exchange Format}].
  179 
  180 [para]
  181 
  182 When used as a result-format this format supports the following
  183 options:
  184 
  185 [include ../modules/pt/include/format/options_json.inc]
  186 
  187 [section {C Parser Embedded In Tcl}]
  188 [include ../modules/pt/include/format/whatis_cparam_critcl.inc]
  189 [para]
  190 
  191 This result-format supports the following options:
  192 
  193 [include ../modules/pt/include/format/options_cparam_critcl.inc]
  194 
  195 [section {C Parser}]
  196 [include ../modules/pt/include/format/whatis_cparam_rawc.inc]
  197 [para]
  198 
  199 This result-format supports the following options:
  200 
  201 [include ../modules/pt/include/format/options_cparam_rawc.inc]
  202 
  203 [section {Snit Parser}]
  204 [include ../modules/pt/include/format/whatis_tclparam_snit.inc]
  205 [para]
  206 
  207 This result-format supports the following options:
  208 
  209 [include ../modules/pt/include/format/options_tclparam_snit.inc]
  210 
  211 [section {TclOO Parser}]
  212 [include ../modules/pt/include/format/whatis_tclparam_oo.inc]
  213 [para]
  214 
  215 This result-format supports the following options:
  216 
  217 [include ../modules/pt/include/format/options_tclparam_oo.inc]
  218 
  219 [section {Grammar Container}]
  220 [include ../modules/pt/include/format/whatis_container.inc]
  221 [para]
  222 
  223 This result-format supports the following options:
  224 
  225 [include ../modules/pt/include/format/options_container.inc]
  226 
  227 [section Example]
  228 [vset MODE app][include ../modules/pt/include/example/full.inc]
  229 
  230 [section Internals]
  231 
  232 This section is intended for users of the application which wish to
  233 modify or extend it. Users only interested in the generation of
  234 parsers can ignore it.
  235 
  236 [para]
  237 
  238 The main functionality of the application is encapsulated in the
  239 package [package pt::pgen]. Please read it for more information.
  240 
  241 [include ../modules/pt/include/feedback.inc]
  242 [manpage_end]