Ubuntu Manpage: page_pluginmgr - page plugin manager

name
synopsis
description
api
config plugin api
reader plugin api
writer plugin api
transform plugin api page::transform::*
predefined plugins
features
bugs, ideas, feedback
keywords
category
copyright

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

       [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::pluginmgr::report (see below) to report
input errors and warnings. The default is to write such reports to the standard error channel.

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

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

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

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

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

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

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

::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 transformation 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 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 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 manager 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 statistics.

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

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

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

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_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 manager 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 statistics.

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_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::pluginmgr::transform. More than one
transformation plugin can be kept in memory.

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

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, and the package it describes, will undoubtedly contain bugs and  other  problems.   Please
       report  such  in the category page of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  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.

KEYWORDS

       page, parser generator, text processing

COPYRIGHT

       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>

NAME

SYNOPSIS

DESCRIPTION

API

CONFIG PLUGIN API

READER PLUGIN API

WRITER PLUGIN API

TRANSFORM PLUGIN API page::transform::*

PREDEFINED PLUGINS

FEATURES

BUGS, IDEAS, FEEDBACK

KEYWORDS

CATEGORY

COPYRIGHT