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
       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_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 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_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 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, 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)
