


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





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


       ::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                           1.0                              2





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


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





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


       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.



page                           1.0                              4





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


              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 plu-
              gin. This is expected to be in doctools format.



page                           1.0                              5





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


       ::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                           1.0                              6





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


       ::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 plu-
              gin. 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                           1.0                              7





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


       ::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                           1.0                              8





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


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





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


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





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


       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



page                           1.0                             11





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


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





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


       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-



page                           1.0                             13





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


                     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



page                           1.0                             14





page_pluginmgr(n)     Parser generator tools    page_pluginmgr(n)


       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                             15


