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

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.

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.

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:

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.

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 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 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 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.

The following predefined plugins are known, i.e. provided by the page
module.

Configuration

peg

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.

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 grammar 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 validation.

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 equivalent 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 initializing a PEG container as
provided by the package grammar::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.

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.

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.