"Fossies" - the Fresh Open Source Software Archive

Member "SAOImageDS9/tcllib/apps/page.man" (13 Nov 2019, 14610 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 {-*- tcl -*- doctools manpage}]
    2 [manpage_begin page n 1.0]
    3 [see_also page::pluginmgr]
    4 [keywords {parser generator}]
    5 [keywords {text processing}]
    6 [copyright {2005 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
    7 [titledesc {Parser Generator}]
    8 [moddesc   {Development Tools}]
    9 [category  {Page Parser Generator}]
   10 [description]
   11 [para]
   12 
   13 The application described by this document, [syscmd page], is actually
   14 not just a parser generator, as the name implies, but a generic tool
   15 for the execution of arbitrary transformations on texts.
   16 
   17 [para]
   18 
   19 Its genericity comes through the use of [term plugins] for reading,
   20 transforming, and writing data, and the predefined set of plugins
   21 provided by Tcllib is for the generation of memoizing recursive
   22 descent parsers (aka [term {packrat parsers}]) from grammar
   23 specifications ([term {Parsing Expression Grammars}]).
   24 
   25 [para]
   26 
   27 [syscmd page] is written on top of the package
   28 
   29 [package page::pluginmgr], wrapping its functionality into a command
   30 line based application. All the other [package page::*] packages are
   31 plugin and/or supporting packages for the generation of parsers. The
   32 parsers themselves are based on the packages [package grammar::peg],
   33 [package grammar::peg::interp], and [package grammar::mengine].
   34 
   35 [subsection {COMMAND LINE}]
   36 
   37 [list_begin definitions]
   38 
   39 [call [cmd page] [opt [arg options]...] [opt "[arg input] [opt [arg output]]"]]
   40 
   41 This is general form for calling [syscmd page]. The application will
   42 read the contents of the file [arg input], process them under the
   43 control of the specified [arg options], and then write the result to
   44 the file [arg output].
   45 
   46 [para]
   47 
   48 If [arg input] is the string [const -] the data to process will be
   49 read from [const stdin] instead of a file. Analogously the result will
   50 be written to [const stdout] instead of a file if [arg output] is the
   51 string [const -]. A missing output or input specification causes the
   52 application to assume [const -].
   53 
   54 [para]
   55 
   56 The detailed specifications of the recognized [arg options] are
   57 provided in section [sectref OPTIONS].
   58 
   59 [list_begin arguments]
   60 [arg_def path input in]
   61 
   62 This argument specifies the path to the file to be processed by the
   63 application, or [const -]. The last value causes the application to
   64 read the text from [const stdin]. Otherwise it has to exist, and be
   65 readable. If the argument is missing [const -] is assumed.
   66 
   67 [arg_def path output in]
   68 
   69 This argument specifies where to write the generated text. It can be
   70 the path to a file, or [const -]. The last value causes the
   71 application to write the generated documented to [const stdout].
   72 
   73 [para]
   74 
   75 If the file [arg output] does not exist then
   76 [lb]file dirname $output[rb] has to exist and must be a writable
   77 directory, as the application will create the fileto write to.
   78 
   79 [para]
   80 
   81 If the argument is missing [const -] is assumed.
   82 
   83 [list_end]
   84 [list_end]
   85 
   86 [subsection OPERATION]
   87 
   88 ... reading ... transforming ... writing - plugins - pipeline ...
   89 
   90 [subsection OPTIONS]
   91 
   92 This section describes all the options available to the user of the
   93 application. Options are always processed in order. I.e. of both
   94 [option --help] and [option --version] are specified the option
   95 encountered first has precedence.
   96 
   97 [para]
   98 
   99 Unknown options specified before any of the options [option -rd],
  100 [option -wr], or [option -tr] will cause processing to abort with an
  101 error. Unknown options coming in between these options, or after the
  102 last of them are assumed to always take a single argument and are
  103 associated with the last plugin option coming before them. They will
  104 be checked after all the relevant plugins, and thus the options they
  105 understand, are known. I.e. such unknown options cause error if and
  106 only if the plugin option they are associated with does not understand
  107 them, and was not superceded by a plugin option coming after.
  108 
  109 [para]
  110 
  111 Default options are used if and only if the command line did not
  112 contain any options at all. They will set the application up as a
  113 PEG-based parser generator. The exact list of options is
  114 
  115 [para]
  116 [example {-c peg}]
  117 [para]
  118 
  119 And now the recognized options and their arguments, if they have any:
  120 
  121 [para]
  122 [list_begin options]
  123 
  124 [opt_def --help]
  125 [opt_def -h]
  126 [opt_def -?]
  127 
  128 When one of these options is found on the command line all arguments
  129 coming before or after are ignored. The application will print a short
  130 description of the recognized options and exit.
  131 
  132 [opt_def --version]
  133 [opt_def -V]
  134 
  135 When one of these options is found on the command line all arguments
  136 coming before or after are ignored. The application will print its
  137 own revision and exit.
  138 
  139 [opt_def -P]
  140 
  141 This option signals the application to activate visual feedback while
  142 reading the input.
  143 
  144 [opt_def -T]
  145 
  146 This option signals the application to collect statistics while
  147 reading the input and to print them after reading has completed,
  148 before processing started.
  149 
  150 [opt_def -D]
  151 
  152 This option signals the application to activate logging in the Safe
  153 base, for the debugging of problems with plugins.
  154 
  155 [opt_def -r parser]
  156 [opt_def -rd parser]
  157 [opt_def --reader parser]
  158 
  159 These options specify the plugin the application has to use for
  160 reading the [arg input]. If the options are used multiple times the
  161 last one will be used.
  162 
  163 [opt_def -w generator]
  164 [opt_def -wr generator]
  165 [opt_def --writer generator]
  166 
  167 These options specify the plugin the application has to use for
  168 generating and writing the final [arg output]. If the options are used
  169 multiple times the last one will be used.
  170 
  171 [opt_def -t process]
  172 [opt_def -tr process]
  173 [opt_def --transform process]
  174 
  175 These options specify a plugin to run on the input. In contrast to
  176 readers and writers each use will [emph not] supersede previous
  177 uses, but add each chosen plugin to a list of transformations, either
  178 at the front, or the end, per the last seen use of either option
  179 [option -p] or [option -a]. The initial default is to append the new
  180 transformations.
  181 
  182 [opt_def -a]
  183 [opt_def --append]
  184 
  185 These options signal the application that all following
  186 transformations should be added at the end of the list of
  187 transformations.
  188 
  189 [opt_def -p]
  190 [opt_def --prepend]
  191 
  192 These options signal the application that all following
  193 transformations should be added at the beginning of the list of
  194 transformations.
  195 
  196 [opt_def --reset]
  197 
  198 This option signals the application to clear the list of
  199 transformations. This is necessary to wipe out the default
  200 transformations used.
  201 
  202 [opt_def -c file]
  203 [opt_def --configuration file]
  204 
  205 This option causes the application to load a configuration file and/or
  206 plugin. This is a plugin which in essence provides a pre-defined set
  207 of commandline options. They are processed exactly as if they have
  208 been specified in place of the option and its arguments. This means
  209 that unknown options found at the beginning of the configuration file
  210 are associated with the last plugin, even if that plugin was specified
  211 before the configuration file itself. Conversely, unknown options
  212 coming after the configuration file can be associated with a plugin
  213 specified in the file.
  214 
  215 [para]
  216 
  217 If the argument is a file which cannot be loaded as a plugin the
  218 application will assume that its contents are a list of options and
  219 their arguments, separated by space, tabs, and newlines. Options and
  220 argumentes containing spaces can be quoted via double-quotes (") and
  221 quotes ('). The quote character can be specified within in a quoted
  222 string by doubling it. Newlines in a quoted string are accepted as is.
  223 
  224 [comment {"}]
  225 [list_end]
  226 
  227 [subsection PLUGINS]
  228 
  229 [syscmd page] makes use of four different types of plugins, namely:
  230 readers, writers, transformations, and configurations. Here we provide
  231 only a basic introduction on how to use them from [syscmd page]. The
  232 exact APIs provided to and expected from the plugins can be found in
  233 the documentation for [package page::pluginmgr], for those who wish to
  234 write their own plugins.
  235 
  236 [para]
  237 
  238 Plugins are specified as arguments to the options [option -r],
  239 [option -w], [option -t], [option -c], and their equivalent longer
  240 forms. See the section [sectref OPTIONS] for reference.
  241 
  242 [para]
  243 
  244 Each such argument will be first treated as the name of a file and
  245 this file is loaded as the plugin. If however there is no file with
  246 that name, then it will be translated into the name of a package, and
  247 this package is then loaded. For each type of plugins the package
  248 management searches not only the regular paths, but a set application-
  249 and type-specific paths as well. Please see the section
  250 [sectref {PLUGIN LOCATIONS}] for a listing of all paths and their
  251 sources.
  252 
  253 [para]
  254 
  255 [list_begin definitions]
  256 [def "[option -c] [arg name]"]
  257 
  258 Configurations. The name of the package for the plugin [arg name] is
  259 "page::config::[arg name]".
  260 
  261 [para]
  262 We have one predefined plugin:
  263 
  264 [list_begin definitions]
  265 [def [emph peg]]
  266 
  267 It sets the application up as a parser generator accepting parsing
  268 expression grammars and writing a packrat parser in Tcl. The actual
  269 arguments it specifies are:
  270 
  271 [para]
  272 [example {
  273 	--reset
  274 	--append
  275 	--reader    peg
  276 	--transform reach
  277 	--transform use
  278 	--writer    me
  279 }]
  280 [para]
  281 
  282 [list_end]
  283 
  284 [def "[option -r] [arg name]"]
  285 
  286 Readers. The name of the package for the plugin [arg name] is
  287 "page::reader::[arg name]".
  288 
  289 [para]
  290 We have five predefined plugins:
  291 
  292 [list_begin definitions]
  293 [def [emph peg]]
  294 
  295 Interprets the input as a parsing expression grammar ([term PEG]) and
  296 generates a tree representation for it. Both the syntax of PEGs and
  297 the structure of the tree representation are explained in their own
  298 manpages.
  299 
  300 [def [emph hb]]
  301 
  302 Interprets the input as Tcl code as generated by the writer plugin
  303 [emph hb] and generates its tree representation.
  304 
  305 [def [emph ser]]
  306 
  307 Interprets the input as the serialization of a PEG, as generated by
  308 the writer plugin [emph ser], using the package
  309 [package grammar::peg].
  310 
  311 [def [emph lemon]]
  312 
  313 Interprets the input as a grammar specification as understood by
  314 Richard Hipp's [term LEMON] parser generator and generates a tree
  315 representation for it. Both the input syntax and the structure of the
  316 tree representation are explained in their own manpages.
  317 
  318 [def [emph treeser]]
  319 
  320 Interprets the input as the serialization of a
  321 [package struct::tree]. It is validated as such,
  322 but nothing else. It is [emph not] assumed to
  323 be the tree representation of a grammar.
  324 [list_end]
  325 
  326 [def "[option -w] [arg name]"]
  327 
  328 Writers. The name of the package for the plugin [arg name] is
  329 "page::writer::[arg name]".
  330 
  331 [para]
  332 We have eight predefined plugins:
  333 
  334 [list_begin definitions]
  335 
  336 [def [emph identity]]
  337 
  338 Simply writes the incoming data as it is, without making any
  339 changes. This is good for inspecting the raw result of a reader or
  340 transformation.
  341 
  342 [def [emph null]]
  343 
  344 Generates nothing, and ignores the incoming data structure.
  345 
  346 [def [emph tree]]
  347 
  348 Assumes that the incoming data structure is a [package struct::tree]
  349 and generates an indented textual representation of all nodes, their
  350 parental relationships, and their attribute information.
  351 
  352 [def [emph peg]]
  353 
  354 Assumes that the incoming data structure is a tree representation of a
  355 [term PEG] or other other grammar and writes it out as a PEG. The
  356 result is nicely formatted and partially simplified (strings as
  357 sequences of characters). A pretty printer in essence, but can also be
  358 used to obtain a canonical representation of the input grammar.
  359 
  360 [def [emph tpc]]
  361 
  362 Assumes that the incoming data structure is a tree representation of a
  363 [term PEG] or other other grammar and writes out Tcl code defining a
  364 package which defines a [package grammar::peg] object containing the
  365 grammar when it is loaded into an interpreter.
  366 
  367 [def [emph hb]]
  368 
  369 This is like the writer plugin [emph tpc], but it writes only the
  370 statements which define stat expression and grammar rules. The code
  371 making the result a package is left out.
  372 
  373 [def [emph ser]]
  374 
  375 Assumes that the incoming data structure is a tree representation of a
  376 [term PEG] or other other grammar, transforms it internally into a
  377 [package grammar::peg] object and writes out its serialization.
  378 
  379 [def [emph me]]
  380 
  381 Assumes that the incoming data structure is a tree representation of a
  382 [term PEG] or other other grammar and writes out Tcl code defining a
  383 package which implements a memoizing recursive descent parser based on
  384 the match engine (ME) provided by the package [package grammar::mengine].
  385 
  386 [list_end]
  387 
  388 [def "[option -t] [arg name]"]
  389 
  390 Transformers. The name of the package for the plugin [arg name] is
  391 "page::transform::[arg name]".
  392 
  393 [para]
  394 We have two predefined plugins:
  395 
  396 [list_begin definitions]
  397 [def [emph reach]]
  398 
  399 Assumes that the incoming data structure is a tree representation of a
  400 [term PEG] or other other grammar. It determines which nonterminal
  401 symbols and rules are reachable from start-symbol/expression. All
  402 nonterminal symbols which were not reached are removed.
  403 
  404 [def [emph use]]
  405 
  406 Assumes that the incoming data structure is a tree representation of a
  407 [term PEG] or other other grammar. It determines which nonterminal
  408 symbols and rules are able to generate a [emph finite] sequences of
  409 terminal symbols (in the sense for a Context Free Grammar). All
  410 nonterminal symbols which were not deemed useful in this sense are
  411 removed.
  412 
  413 [list_end]
  414 [list_end]
  415 
  416 [subsection {PLUGIN LOCATIONS}]
  417 
  418 The application-specific paths searched by [syscmd page] either are,
  419 or come from:
  420 
  421 [para]
  422 
  423 [list_begin enumerated]
  424 [enum] The directory            [file ~/.page/plugin]
  425 [enum] The environment variable [term PAGE_PLUGINS]
  426 [enum] The registry entry       [term "HKEY_LOCAL_MACHINE\\SOFTWARE\\PAGE\\PLUGINS"]
  427 [enum] The registry entry       [term "HKEY_CURRENT_USER\\SOFTWARE\\PAGE\\PLUGINS"]
  428 [list_end]
  429 
  430 [para]
  431 
  432 The type-specific paths searched by [syscmd page] either are, or come
  433 from:
  434 
  435 [para]
  436 [list_begin enumerated]
  437 [enum] The directory            [file ~/.page/plugin/<TYPE>]
  438 [enum] The environment variable [term PAGE_<TYPE>_PLUGINS]
  439 [enum] The registry entry       [term "HKEY_LOCAL_MACHINE\\SOFTWARE\\PAGE\\<TYPE>\\PLUGINS"]
  440 [enum] The registry entry       [term "HKEY_CURRENT_USER\\SOFTWARE\\PAGE\\<TYPE>\\PLUGINS"]
  441 [list_end]
  442 
  443 [para]
  444 
  445 Where the placeholder [term <TYPE>] is always one of the values below,
  446 properly capitalized.
  447 
  448 [list_begin enumerated]
  449 [enum] reader
  450 [enum] writer
  451 [enum] transform
  452 [enum] config
  453 [list_end]
  454 [para]
  455 
  456 The registry entries are specific to the Windows(tm) platform, all
  457 other platforms will ignore them.
  458 
  459 [para]
  460 
  461 The contents of both environment variables and registry entries are
  462 interpreted as a list of paths, with the elements separated by either
  463 colon (Unix), or semicolon (Windows).
  464 
  465 [vset CATEGORY page]
  466 [include ../modules/doctools2base/include/feedback.inc]
  467 [manpage_end]