page_pluginmgr(n) Parser generator tools page_pluginmgr(n) ______________________________________________________________________________
NAME
page_pluginmgr - page plugin manager
SYNOPSIS
package require page::pluginmgr ?0.2?
package require fileutil
::page::pluginmgr::reportvia cmd
::page::pluginmgr::report level text ?from ?to??
::page::pluginmgr::log cmd
::page::pluginmgr::configuration name
::page::pluginmgr::reader name
::page::pluginmgr::rconfigure dict
::page::pluginmgr::rtimeable
::page::pluginmgr::rtime
::page::pluginmgr::rgettime
::page::pluginmgr::rhelp
::page::pluginmgr::rlabel
::page::pluginmgr::read read eof ?complete?
read num
eof
done
::page::pluginmgr::writer name
::page::pluginmgr::wconfigure dict
::page::pluginmgr::wtimeable
::page::pluginmgr::wtime
::page::pluginmgr::wgettime
::page::pluginmgr::whelp
::page::pluginmgr::wlabel
::page::pluginmgr::write chan data
::page::pluginmgr::transform name
::page::pluginmgr::tconfigure id dict
::page::pluginmgr::ttimeable id
::page::pluginmgr::ttime id
::page::pluginmgr::tgettime id
::page::pluginmgr::thelp id
::page::pluginmgr::tlabel id
::page::pluginmgr::transform_do id data
page_cdefinition
page_rfeature name
page_rtime
page_rgettime
page_rlabel
page_rhelp
page_roptions
page_rconfigure option value
page_rrun
page_read num
page_read_done
page_eof
page_info text ?from ?to??
page_warning text ?from ?to??
page_error text ?from ?to??
page_log_info text
page_log_warning text
page_log_error text
page_wfeature
page_wtime
page_wgettime
page_wlabel
page_whelp
page_woptions
page_wconfigure option value
page_wrun chan data
page_info text ?from ?to??
page_warning text ?from ?to??
page_error text ?from ?to??
page_log_info text
page_log_warning text
page_log_error text
page_tfeature
page_ttime
page_tgettime
page_tlabel
page_thelp
page_toptions
page_tconfigure option value
page_trun chan data
page_info text ?from ?to??
page_warning text ?from ?to??
page_error text ?from ?to??
page_log_info text
page_log_warning text
page_log_error text
_________________________________________________________________
DESCRIPTION
This package provides the plugin manager central to the page applica-
tion. It manages the various reader, writer, configuration, and trans-
formation 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 environ-
ment 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
[1] CONFIG PLUGIN API
[2] READER PLUGIN API
[3] WRITER PLUGIN API
[4] TRANSFORM PLUGIN API
as per their type.
API
::page::pluginmgr::reportvia cmd
This command defines the callback command used by ::page::plug-
inmgr::report (see below) to report input errors and warnings.
The default is to write such reports to the standard error chan-
nel.
::page::pluginmgr::report level text ?from ?to??
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.
::page::pluginmgr::log cmd
This command defines a log callback command to be used by loaded
plugins for the reporting of internal errors, warnings, and gen-
eral information. Specifying the empty string as callback dis-
ables 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.
::page::pluginmgr::configuration name
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, sep-
arated by spaces, tabs and newlines, possibly quotes with single
and double quotes.
See section CONFIG PLUGIN API for the API expected of configura-
tion plugins.
The result of the command is the list of options retrieved.
::page::pluginmgr::reader name
This command loads the named reader plugin and initializes it.
The result of the command is a list of options the plugin under-
stands.
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.
::page::pluginmgr::rconfigure dict
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.
::page::pluginmgr::rtimeable
This commands checks if the loaded reader plugin is able to col-
lect timing statistics. The result of the command is a boolean
flag. The result is true if the plugin can be timed, and false
otherwise.
::page::pluginmgr::rtime
This command activates the collection of timing statistics in
the loaded reader plugin.
::page::pluginmgr::rgettime
This command retrieves the collected timing statistics of the
loaded reader plugin after it was executed.
::page::pluginmgr::rhelp
This command retrieves the help string of the loaded reader
plugin. This is expected to be in doctools format.
::page::pluginmgr::rlabel
This command retrieves the human-readable name of the loaded
reader plugin.
::page::pluginmgr::read read eof ?complete?
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 pre-
fixes.
The plugin will invoke the various callbacks in the following
situations:
read num
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.
eof 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.
done is invoked when the plugin has completed the processing
of the input.
::page::pluginmgr::writer name
This command loads the named writer plugin and initializes it.
The result of the command is a list of options the plugin under-
stands.
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.
::page::pluginmgr::wconfigure dict
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.
::page::pluginmgr::wtimeable
This commands checks if the loaded writer plugin is able to mea-
sure execution times. The result of the command is a boolean
flag. The result is true if the plugin can be timed, and false
otherwise.
::page::pluginmgr::wtime
This command activates the collection of timing statistics in
the loaded writer plugin.
::page::pluginmgr::wgettime
This command retrieves the collected timing statistics of the
loaded writer plugin after it was executed.
::page::pluginmgr::whelp
This command retrieves the help string of the loaded writer
plugin. This is expected to be in doctools format.
::page::pluginmgr::wlabel
This command retrieves the human-readable name of the loaded
writer plugin.
::page::pluginmgr::write chan data
The loaded writer plugin is invoked to generate the output. It
is given the data to generate the outpout from, and the Tcl han-
dle chan of the channel to write the generated output to. The
command returns th empty string as its result.
::page::pluginmgr::transform name
This command loads the named transformation plugin and initial-
izes it. The result of the command is a 2-element list contain-
ing the plugin id and a list of options the plugin understands,
in this order.
Multiple transformations plugins can be loaded and are identi-
fied by handles.
See section TRANSFORM PLUGIN API for the API expected of trans-
formation plugins.
::page::pluginmgr::tconfigure id dict
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.
::page::pluginmgr::ttimeable id
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.
::page::pluginmgr::ttime id
This command activates the collection of timing statistics in
the identified transformation plugin.
::page::pluginmgr::tgettime id
This command retrieves the collected timing statistics of the
identified transformation plugin after it was executed.
::page::pluginmgr::thelp id
This command retrieves the help string of the identified trans-
formation plugin. This is expected to be in doctools format.
::page::pluginmgr::tlabel id
This command retrieves the human-readable name of the identified
transformation plugin.
::page::pluginmgr::transform_do id data
The identified transformation plugin is invoked to process the
specified data. The result of the plugin is returned as the
result of the command.
CONFIG PLUGIN API
Configuration plugins are expected to provide a single command,
described below.
page_cdefinition
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 spe-
cial 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 PLUGIN API
Reader plugins are expected to provide the following commands,
described below.
page_rfeature name
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 man-
ager will ask for.
page_rtime
This command is invoked to activate the collection of timing
statistics.
page_rgettime
This command is invoked to retrieve the collected timing statis-
tics.
page_rlabel
This command is invoked to retrieve a human-readable label for
the plugin.
page_rhelp
This command is invoked to retrieve a help text for plugin. The
text is expected to be in doctools format.
page_roptions
This command is invoked to retrieve the options understood by
the plugin.
page_rconfigure option value
This command is invoked to reconfigure the plugin, specifically
the given option is set to the new value.
page_rrun
This command is invoked to process the input stream per the cur-
rent plugin configuration. The result of the command is the
result of the processing.
Reader plugins expect the environment to provide the following special
commands.
page_read num
This command is invoked to read num characters/bytes from the
input. Its result has to be read characters/bytes.
page_read_done
This command is invoked to signal that the plugin has completed
the processing of the input.
page_eof
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.
page_info text ?from ?to??
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 num-
bers.
page_warning text ?from ?to??
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.
page_error text ?from ?to??
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.
page_log_info text
Invoked to report some internal information.
page_log_warning text
Invoked to report an internal warning.
page_log_error text
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 PLUGIN API
Writer plugins are expected to provide the following commands,
described below.
page_wfeature
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 man-
ager will ask for.
page_wtime
This command is invoked to activate the collection of timing
statistics.
page_wgettime
This command is invoked to retrieve the collected timing statis-
tics.
page_wlabel
This command is invoked to retrieve a human-readable label for
the plugin.
page_whelp
This command is invoked to retrieve a help text for plugin. The
text is expected to be in doctools format.
page_woptions
This command is invoked to retrieve the options understood by
the plugin.
page_wconfigure option value
This command is invoked to reconfigure the plugin, specifically
the given option is set to the new value.
page_wrun chan data
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.
page_info text ?from ?to??
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 num-
bers.
page_warning text ?from ?to??
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.
page_error text ?from ?to??
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.
page_log_info text
Invoked to report some internal information.
page_log_warning text
Invoked to report an internal warning.
page_log_error text
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.
TRANSFORM PLUGIN API page::transform::*
Transformation plugins are expected to provide the following commands,
described below.
page_tfeature
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 man-
ager will ask for.
page_ttime
This command is invoked to activate the collection of timing
statistics.
page_tgettime
This command is invoked to retrieve the collected timing statis-
tics.
page_tlabel
This command is invoked to retrieve a human-readable label for
the plugin.
page_thelp
This command is invoked to retrieve a help text for plugin. The
text is expected to be in doctools format.
page_toptions
This command is invoked to retrieve the options understood by
the plugin.
page_tconfigure option value
This command is invoked to reconfigure the plugin, specifically
the given option is set to the new value.
page_trun chan data
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.
page_info text ?from ?to??
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 num-
bers.
page_warning text ?from ?to??
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.
page_error text ?from ?to??
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.
page_log_info text
Invoked to report some internal information.
page_log_warning text
Invoked to report an internal warning.
page_log_error text
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::plugin-
mgr::transform. More than one transformation plugin can be kept in mem-
ory.
PREDEFINED PLUGINS
The following predefined plugins are known, i.e. provided by the page
module.
Configuration
peg Returns a set of options to configure the page applica-
tion for the processing of a PEG grammar and the genera-
tion of ME code. See the packages grammar_peg, grammar_me
and relations for more details.
Reader
hb 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.
lemon Expects a grammar specification as understood by Richar
Hipp's LEMON parser generator and returns an abstract
syntax tree for it.
peg Expects a grammar specification in the form of a parsing
expression grammar (PEG) and returns an abstract syntax
tree for it.
ser Expect the serialized form of a parsing expression gram-
mar as generated by the package grammar::peg as input,
converts it into an equivalent abstract syntax tree and
returns that.
treeser
Expects the serialized form of a tree as generated by the
package struct::tree as input and returns it, after vali-
dation.
Writer
hb 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.
identity
Takes any input and writes it as is.
mecpu 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.
me 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.
null Takes any input and writes nothing. The logical equiva-
lent of /dev/null.
peg 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.
ser 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.
tpc Expects an abstract syntax tree for a parsing expression
grammar as input and writes it out as Tcl code initializ-
ing a PEG container as provided by the package gram-
mar::peg.
tree Takes any serialized tree (per package struct::tree) as
input and writes it out in a generic indented format.
Transformation
mecpu 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).
reachable
Takes an abstract syntax tree for a parsing expression
grammer as input, performs a reachability analysis, and
returns the modified and annotated tree.
realizable
Takes an abstract syntax tree for a parsing expression
grammer as input, performs an analysis of realizability,
and returns the modified and annotated tree.
FEATURES
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.
BUGS, IDEAS, FEEDBACK
This document, will undoubtedly contain bugs and other problems.
Please report such in the category page of the Tcllib SF Trackers
[http://sourceforge.net/tracker/?group_id=12883]. Please also report
any ideas for enhancements you may have.
KEYWORDS
page, parser generator, text processing
CATEGORY
Page Parser Generator
COPYRIGHT
Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
page 1.0 page_pluginmgr(n)
Mac OS X 10.8 - Generated Mon Sep 10 16:31:35 CDT 2012