Scroll to navigation

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





NAME


page_pluginmgr - page plugin manager






SYNOPSIS


package require page::pluginmgr ?0.3?


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:

  







  

  
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.

  

  
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.

  

  
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.



  

  
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.



  

  
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.

  

  

  
This command is invoked to activate the collection of timing
    statistics.

  

  
This command is invoked to retrieve the collected timing statistics.

  

  
This command is invoked to retrieve a human-readable label for the
    plugin.

  

  
This command is invoked to retrieve a help text for plugin. The text is
      expected to be in doctools format.

  

  
This command is invoked to retrieve the options understood by the
    plugin.

  

  
This command is invoked to reconfigure the plugin, specifically the given
      option is set to the new value.

  

  
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.



  

  
This command is invoked to read num characters/bytes from the
      input. Its result has to be read characters/bytes.

  

  
This command is invoked to signal that the plugin has completed the
      processing of the input.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
Invoked to report some internal information.

  

  
Invoked to report an internal warning.

  

  
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.



  

  
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.

  

  

  
This command is invoked to activate the collection of timing
    statistics.

  

  
This command is invoked to retrieve the collected timing statistics.

  

  
This command is invoked to retrieve a human-readable label for the
    plugin.

  

  
This command is invoked to retrieve a help text for plugin. The text is
      expected to be in doctools format.

  

  
This command is invoked to retrieve the options understood by the
    plugin.

  

  
This command is invoked to reconfigure the plugin, specifically the given
      option is set to the new value.

  

  
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.



  

  
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.

  

  
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.

  

  
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.

  

  
Invoked to report some internal information.

  

  
Invoked to report an internal warning.

  

  
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.



  

  
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.

  

  

  
This command is invoked to activate the collection of timing
    statistics.

  

  
This command is invoked to retrieve the collected timing statistics.

  

  
This command is invoked to retrieve a human-readable label for the
    plugin.

  

  
This command is invoked to retrieve a help text for plugin. The text is
      expected to be in doctools format.

  

  
This command is invoked to retrieve the options understood by the
    plugin.

  

  
This command is invoked to reconfigure the plugin, specifically the given
      option is set to the new value.

  

  
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.



  

  
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.

  

  
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.

  

  
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.

  

  
Invoked to report some internal information.

  

  
Invoked to report an internal warning.

  

  
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.



  

  







  

  
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.







  

  







  

  
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.

  

  
Expects a grammar specification as understood by Richar Hipp's LEMON
      parser generator and returns an abstract syntax tree for it.

  

  
Expects a grammar specification in the form of a parsing expression
      grammar (PEG) and returns an abstract syntax tree for it.

  

  
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.

  

  
Expects the serialized form of a tree as generated by the package
      struct::tree as input and returns it, after validation.







  

  







  

  
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.

  

  
Takes any input and writes it as is.

  

  
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.

  

  
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.

  

  
Takes any input and writes nothing. The logical equivalent of
    /dev/null.

  

  
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.

  

  
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.

  

  
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.

  

  
Takes any serialized tree (per package struct::tree) as input and
      writes it out in a generic indented format.







  

  







  

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

  

  
Takes an abstract syntax tree for a parsing expression grammer as input,
      performs a reachability analysis, and returns the modified and annotated
      tree.

  

  
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>








  

    1.0
    tcllib