Tcl Library Source Code

Documentation
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

page - Parser Generator

Table Of Contents

SYNOPSIS

page ?options...? ?input ?output??

DESCRIPTION

The application described by this document, page, is actually not just a parser generator, as the name implies, but a generic tool for the execution of arbitrary transformations on texts.

Its genericity comes through the use of plugins for reading, transforming, and writing data, and the predefined set of plugins provided by Tcllib is for the generation of memoizing recursive descent parsers (aka packrat parsers) from grammar specifications (Parsing Expression Grammars).

page is written on top of the package page::pluginmgr, wrapping its functionality into a command line based application. All the other page::* packages are plugin and/or supporting packages for the generation of parsers. The parsers themselves are based on the packages grammar::peg, grammar::peg::interp, and grammar::mengine.

COMMAND LINE

OPERATION

... reading ... transforming ... writing - plugins - pipeline ...

OPTIONS

This section describes all the options available to the user of the application. Options are always processed in order. I.e. of both --help and --version are specified the option encountered first has precedence.

Unknown options specified before any of the options -rd, -wr, or -tr will cause processing to abort with an error. Unknown options coming in between these options, or after the last of them are assumed to always take a single argument and are associated with the last plugin option coming before them. They will be checked after all the relevant plugins, and thus the options they understand, are known. I.e. such unknown options cause error if and only if the plugin option they are associated with does not understand them, and was not superceded by a plugin option coming after.

Default options are used if and only if the command line did not contain any options at all. They will set the application up as a PEG-based parser generator. The exact list of options is

-c peg

And now the recognized options and their arguments, if they have any:

PLUGINS

page makes use of four different types of plugins, namely: readers, writers, transformations, and configurations. Here we provide only a basic introduction on how to use them from page. The exact APIs provided to and expected from the plugins can be found in the documentation for page::pluginmgr, for those who wish to write their own plugins.

Plugins are specified as arguments to the options -r, -w, -t, -c, and their equivalent longer forms. See the section OPTIONS for reference.

Each such argument will be first treated as the name of a file and this file is loaded as the plugin. If however there is no file with that name, then it will be translated into the name of a package, and this package is then loaded. For each type of plugins the package management searches not only the regular paths, but a set application- and type-specific paths as well. Please see the section PLUGIN LOCATIONS for a listing of all paths and their sources.

PLUGIN LOCATIONS

The application-specific paths searched by page either are, or come from:

  1. The directory "~/.page/plugin"

  2. The environment variable PAGE_PLUGINS

  3. The registry entry HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\PLUGINS

  4. The registry entry HKEY_CURRENT_USER\SOFTWARE\PAGE\PLUGINS

The type-specific paths searched by page either are, or come from:

  1. The directory "~/.page/plugin/"

  2. The environment variable PAGE__PLUGINS

  3. The registry entry HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\\PLUGINS

  4. The registry entry HKEY_CURRENT_USER\SOFTWARE\PAGE\\PLUGINS

Where the placeholder is always one of the values below, properly capitalized.

  1. reader

  2. writer

  3. transform

  4. config

The registry entries are specific to the Windows(tm) platform, all other platforms will ignore them.

The contents of both environment variables and registry entries are interpreted as a list of paths, with the elements separated by either colon (Unix), or semicolon (Windows).

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category page of the Tcllib Trackers. 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 output 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.

SEE ALSO

page::pluginmgr

KEYWORDS

parser generator, text processing

CATEGORY

Page Parser Generator

COPYRIGHT

Copyright © 2005 Andreas Kupries