Provided by: tcllib_1.21+dfsg-1_all bug

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

CATEGORY

       Page Parser Generator

COPYRIGHT

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