page_pluginmgr - page plugin manager
This package provides the plugin manager central to the page application. It manages the various reader, writer, configuration, and transformation plugins which actually process the text (read, transform, and write).
All plugins are loaded into slave interpreters specially prepared for them. While implemented using packages they need this special environment and are not usable in a plain interpreter, like tclsh. Because of that they are only described in general terms in section PREDEFINED PLUGINS, and not documented as regular packages. It is expected that they follow the APIs specified in the sections
as per their type.
This command defines the callback command used by ::page::pluginmgr::report (see below) to report input errors and warnings. The default is to write such reports to the standard error channel.
This command is used to report input errors and warnings. By default such reports are written to the standard error. This can be changed by setting a user-specific callback command with ::page::pluginmgr::reportvia (see above).
The arguments level and text specify both the importance of the message, and the message itself. For the former see the package logger for the allowed values.
The optional argument from and to can be used by the caller to indicate the location (or range) in the input where the reported problem occured. Each is a list containing two elements, the line and the column in the input, in this order.
This command defines a log callback command to be used by loaded plugins for the reporting of internal errors, warnings, and general information. Specifying the empty string as callback disables logging.
Note: The cmd has to be created by the logger package, or follow the same API as such.
The command returns the empty string as its result.
This command loads the named configuration plugin, retrieves the options encoded in it, and then immediately unloads it again.
If the name is the path to a file, then this files will be tried to be loaded as a plugin first, and, if that fails, opened and its contents read as a list of options and their arguments, separated by spaces, tabs and newlines, possibly quotes with single and double quotes.
See section CONFIG PLUGIN API for the API expected of configuration plugins.
The result of the command is the list of options retrieved.
This command loads the named reader plugin and initializes it. The result of the command is a list of options the plugin understands.
Only a single reader plugin can be loaded. Loading another reader plugin causes the previously loaded reader plugin to be de-initialized and unloaded.
See section READER PLUGIN API for the API expected of reader plugins.
This commands configures the loaded reader plugin. The options and their values are provided as a Tcl dictionary. The result of the command is the empty string.
This commands checks if the loaded reader plugin is able to collect timing statistics. The result of the command is a boolean flag. The result is true if the plugin can be timed, and false otherwise.
This command activates the collection of timing statistics in the loaded reader plugin.
This command retrieves the collected timing statistics of the loaded reader plugin after it was executed.
This command retrieves the help string of the loaded reader plugin. This is expected to be in doctools format.
This command retrieves the human-readable name of the loaded reader plugin.
This command invokes the loaded reader plugin to process the input, and returns the results of the plugin as its own result. The input is accessible through the callback commands read, and eof. The optional done can be used to intrecept when the plugin has completed its processing. All arguments are command prefixes.
The plugin will invoke the various callbacks in the following situations:
is invoked whenever input to process is needed, with the number of characters/bytes it asks for. The result is expected to be the input the plugin is in need of.
is invoked by the plugin to check if the input has reached the of the stream. The result is expected to be a boolean flag, true when the input has hit EOF, and false otherwise.
is invoked when the plugin has completed the processing of the input.
This command loads the named writer plugin and initializes it. The result of the command is a list of options the plugin understands.
Only a single reader plugin can be loaded. Loading another reader plugin causes the previously loaded reader plugin to be de-initialized and unloaded.
See section WRITER PLUGIN API for the API expected of writer plugins.
This commands configures the loaded writer plugin. The options and their values are provided as a Tcl dictionary. The result of the command is the empty string.
This commands checks if the loaded writer plugin is able to measure execution times. The result of the command is a boolean flag. The result is true if the plugin can be timed, and false otherwise.
This command activates the collection of timing statistics in the loaded writer plugin.
This command retrieves the collected timing statistics of the loaded writer plugin after it was executed.
This command retrieves the help string of the loaded writer plugin. This is expected to be in doctools format.
This command retrieves the human-readable name of the loaded writer plugin.
The loaded writer plugin is invoked to generate the output. It is given the data to generate the outpout from, and the Tcl handle chan of the channel to write the generated output to. The command returns th empty string as its result.
This command loads the named transformation plugin and initializes it. The result of the command is a 2-element list containing the plugin id and a list of options the plugin understands, in this order.
Multiple transformations plugins can be loaded and are identified by handles.
See section TRANSFORM PLUGIN API for the API expected of transformation plugins.
This commands configures the identified transformation plugin. The options and their values are provided as a Tcl dictionary. The result of the command is the empty string.
This commands checks if the identified transformation plugin is able to collect timing statistics. The result of the command is a boolean flag. The result is true if the plugin can be timed, and false otherwise.
This command activates the collection of timing statistics in the identified transformation plugin.
This command retrieves the collected timing statistics of the identified transformation plugin after it was executed.
This command retrieves the help string of the identified transformation plugin. This is expected to be in doctools format.
This command retrieves the human-readable name of the identified transformation plugin.
The identified transformation plugin is invoked to process the specified data. The result of the plugin is returned as the result of the command.
Configuration plugins are expected to provide a single command, described below.
This command of a configuration plugin is called by the plugin manager to execute it. Its result has to be a list of options and values to process.
Configuration plugins do not expect the environment to provide any special commands.
It is expected that a configuration plugin FOO is implemented by the package page::config::FOO.
Configuration plugins are loaded, executed, and unloaded in one step, they are not kept in memory. The command for doing this is ::page::pluginmgr::configuration.
Reader plugins are expected to provide the following commands, described below.
This command takes a feature name and returns a boolean flag indicating whether the feature is supported by the plugin, or not. The result has to be true if the feature is supported, and false otherwise.
See section FEATURES for the possible features the plugin manager will ask for.
This command is invoked to activate the collection of timing statistics.
This command is invoked to retrieve the collected timing statistics.
This command is invoked to retrieve a human-readable label for the plugin.
This command is invoked to retrieve a help text for plugin. The text is expected to be in doctools format.
This command is invoked to retrieve the options understood by the plugin.
This command is invoked to reconfigure the plugin, specifically the given option is set to the new value.
This command is invoked to process the input stream per the current plugin configuration. The result of the command is the result of the processing.
Reader plugins expect the environment to provide the following special commands.
This command is invoked to read num characters/bytes from the input. Its result has to be read characters/bytes.
This command is invoked to signal that the plugin has completed the processing of the input.
This command is invoked to check if the input stream has reached its end. Its result has to be a boolean flag, true when the input has reached the end, false otherwise.
Invoked to report some information to the user. May indicate a location or range in the input. Each piece of location data, if provided, is a 2-element list containing line and column numbers.
Invoked to report a warning to the user. May indicate a location or range in the input. Each piece of location data, if provided, is a 2-element list containing line and column numbers.
Invoked to report an error to the user. May indicate a location or range in the input. Each piece of location data, if provided, is a 2-element list containing line and column numbers.
Invoked to report some internal information.
Invoked to report an internal warning.
Invoked to report an internal error.
It is expected that a reader plugin FOO is implemented by the package page::reader::FOO.
Reader plugins are loaded by the command ::page::pluginmgr::reader. At most one reader plugin can be kept in memory.
Writer plugins are expected to provide the following commands, described below.
This command takes a feature name and returns a boolean flag indicating whether the feature is supported by the plugin, or not. The result has to be true if the feature is supported, and false otherwise.
See section FEATURES for the possible features the plugin manager will ask for.
This command is invoked to activate the collection of timing statistics.
This command is invoked to retrieve the collected timing statistics.
This command is invoked to retrieve a human-readable label for the plugin.
This command is invoked to retrieve a help text for plugin. The text is expected to be in doctools format.
This command is invoked to retrieve the options understood by the plugin.
This command is invoked to reconfigure the plugin, specifically the given option is set to the new value.
This command is invoked to process the specified data and write it to the output stream chan. The latter is a Tcl channel handle opened for writing. The result of the command is the empty string.
Writer plugins expect the environment to provide the following special commands.
Invoked to report some information to the user. May indicate a location or range in the input. Each piece of location data, if provided, is a 2-element list containing line and column numbers.
Invoked to report a warning to the user. May indicate a location or range in the input. Each piece of location data, if provided, is a 2-element list containing line and column numbers.
Invoked to report an error to the user. May indicate a location or range in the input. Each piece of location data, if provided, is a 2-element list containing line and column numbers.
Invoked to report some internal information.
Invoked to report an internal warning.
Invoked to report an internal error.
It is expected that a writer plugin FOO is implemented by the package page::writer::FOO.
Writer plugins are loaded by the command ::page::pluginmgr::writer. At most one writer plugin can be kept in memory.
page::transform::* Transformation plugins are expected to provide the following commands, described below.
This command takes a feature name and returns a boolean flag indicating whether the feature is supported by the plugin, or not. The result has to be true if the feature is supported, and false otherwise.
See section FEATURES for the possible features the plugin manager will ask for.
This command is invoked to activate the collection of timing statistics.
This command is invoked to retrieve the collected timing statistics.
This command is invoked to retrieve a human-readable label for the plugin.
This command is invoked to retrieve a help text for plugin. The text is expected to be in doctools format.
This command is invoked to retrieve the options understood by the plugin.
This command is invoked to reconfigure the plugin, specifically the given option is set to the new value.
This command is invoked to process the specified data and write it to the output stream chan. The latter is a Tcl channel handle opened for writing. The result of the command is the empty string.
Transformation plugins expect the environment to provide the following special commands.
Invoked to report some information to the user. May indicate a location or range in the input. Each piece of location data, if provided, is a 2-element list containing line and column numbers.
Invoked to report a warning to the user. May indicate a location or range in the input. Each piece of location data, if provided, is a 2-element list containing line and column numbers.
Invoked to report an error to the user. May indicate a location or range in the input. Each piece of location data, if provided, is a 2-element list containing line and column numbers.
Invoked to report some internal information.
Invoked to report an internal warning.
Invoked to report an internal error.
It is expected that a transformation plugin FOO is implemented by the package page::transform::FOO.
Transformation plugins are loaded by the command ::page::pluginmgr::transform. More than one transformation plugin can be kept in memory.
The following predefined plugins are known, i.e. provided by the page module.
Returns a set of options to configure the page application for the processing of a PEG grammar and the generation of ME code. See the packages grammar_peg, grammar_me and relations for more details.
Expects a so-called half-baked PEG container as input and returns the equivalent abstract syntax tree. See the writer plugin hb for the plugin generating this type of input.
Expects a grammar specification as understood by Richar Hipp's LEMON parser generator and returns an abstract syntax tree for it.
Expects a grammar specification in the form of a parsing expression grammar (PEG) and returns an abstract syntax tree for it.
Expect the serialized form of a parsing expression grammar as generated by the package grammar::peg as input, converts it into an equivalent abstract syntax tree and returns that.
Expects the serialized form of a tree as generated by the package struct::tree as input and returns it, after validation.
Expects an abstract syntax tree for a parsing expression grammar as input and writes it out in the form of a so-called half-baked PEG container.
Takes any input and writes it as is.
Expects symbolic assembler code for the MatchEngine CPU (See the package grammar::me::cpu and relatives) and writes it out as Tcl code for a parser.
Expects an abstract syntax tree for a parsing expression grammar as input and writes it out as Tcl code for the MatchEngine (See the package grammar::me and relatives) which parses input in that grammar.
Takes any input and writes nothing. The logical equivalent of /dev/null.
Expects an abstract syntax tree for a parsing expression grammar as input and writes it out in the form of a canonical PEG which can be read by the reader plugin peg.
Expects an abstract syntax tree for a parsing expression grammar as input and writes it out as a serialized PEG container which can be read by the reader plugin ser.
Expects an abstract syntax tree for a parsing expression grammar as input and writes it out as Tcl code initializing a PEG container as provided by the package grammar::peg.
Takes any serialized tree (per package struct::tree) as input and writes it out in a generic indented format.
Takes an abstract syntax tree for a parsing expression grammer as input, generates symbolic assembler code for the MatchEngine CPU, and returns that as its result (See the package grammar::me::cpu and relatives).
Takes an abstract syntax tree for a parsing expression grammer as input, performs a reachability analysis, and returns the modified and annotated tree.
Takes an abstract syntax tree for a parsing expression grammer as input, performs an analysis of realizability, and returns the modified and annotated tree.
The plugin manager currently checks the plugins for only one feature, timeable. A plugin supporting this feature is assumed to be able to collect timing statistics on request.
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.
Page Parser Generator
Copyright © 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>