page_pluginmgr(3)



page_pluginmgr(3tcl)        Parser generator tools        page_pluginmgr(3tcl)

______________________________________________________________________________

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

              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
              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 in-
              put,  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 ex-
                     pected 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::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 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::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  re-
              sult of the command.

CONFIG PLUGIN API
       Configuration  plugins  are  expected  to provide a single command, de-
       scribed 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,  de-
       scribed below.

       page_rfeature name
              This command takes a feature name and returns a boolean flag in-
              dicating 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_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 re-
              sult 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 in-
              put 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_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, de-
       scribed below.

       page_wfeature
              This command takes a feature name and returns a boolean flag in-
              dicating 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_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 in-
              dicating 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_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_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-
                     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
       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 out-
       put 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>

tcllib                                1.0                 page_pluginmgr(3tcl)

Man(1) output converted with man2html
list of all man pages