<html><head>
<title>page_pluginmgr - Parser generator tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.toc,UL.toc UL, UL.toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.section, LI.subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.requirements LI, UL.syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
--></style>
</head>
<! -- Generated from file 'page_pluginmgr.man' by tcllib/doctools with format 'html'
-->
<! -- Copyright © 2007 Andreas Kupries <[email protected]>
-->
<! -- CVS: $Id$ page_pluginmgr.n
-->
<body><div class="doctools">
<hr> [
<a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<h1 class="title">page_pluginmgr(n) 1.0 tcllib "Parser generator tools"</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>page_pluginmgr - page plugin manager</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#synopsis">Synopsis</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">API</a></li>
<li class="section"><a href="#section3">CONFIG PLUGIN API</a></li>
<li class="section"><a href="#section4">READER PLUGIN API</a></li>
<li class="section"><a href="#section5">WRITER PLUGIN API</a></li>
<li class="section"><a href="#section6">TRANSFORM PLUGIN API</a></li>
<li class="section"><a href="#section7">PREDEFINED PLUGINS</a></li>
<li class="section"><a href="#section8">FEATURES</a></li>
<li class="section"><a href="#section9">Bugs, Ideas, Feedback</a></li>
<li class="section"><a href="#keywords">Keywords</a></li>
<li class="section"><a href="#category">Category</a></li>
<li class="section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="synopsis">
<ul class="requirements">
<li>package require <b class="pkgname">page::pluginmgr <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">fileutil</b></li>
</ul>
<ul class="syntax">
<li><a href="#1"><b class="cmd">::page::pluginmgr::reportvia</b> <i class="arg">cmd</i></a></li>
<li><a href="#2"><b class="cmd">::page::pluginmgr::report</b> <i class="arg">level</i> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#3"><b class="cmd">::page::pluginmgr::log</b> <i class="arg">cmd</i></a></li>
<li><a href="#4"><b class="cmd">::page::pluginmgr::configuration</b> <i class="arg">name</i></a></li>
<li><a href="#5"><b class="cmd">::page::pluginmgr::reader</b> <i class="arg">name</i></a></li>
<li><a href="#6"><b class="cmd">::page::pluginmgr::rconfigure</b> <i class="arg">dict</i></a></li>
<li><a href="#7"><b class="cmd">::page::pluginmgr::rtimeable</b></a></li>
<li><a href="#8"><b class="cmd">::page::pluginmgr::rtime</b></a></li>
<li><a href="#9"><b class="cmd">::page::pluginmgr::rgettime</b></a></li>
<li><a href="#10"><b class="cmd">::page::pluginmgr::rhelp</b></a></li>
<li><a href="#11"><b class="cmd">::page::pluginmgr::rlabel</b></a></li>
<li><a href="#12"><b class="cmd">::page::pluginmgr::read</b> <i class="arg">read</i> <i class="arg">eof</i> <span class="opt">?<i class="arg">complete</i>?</span></a></li>
<li><a href="#13"><i class="arg">read</i> <i class="arg">num</i></a></li>
<li><a href="#14"><i class="arg">eof</i></a></li>
<li><a href="#15"><i class="arg">done</i></a></li>
<li><a href="#16"><b class="cmd">::page::pluginmgr::writer</b> <i class="arg">name</i></a></li>
<li><a href="#17"><b class="cmd">::page::pluginmgr::wconfigure</b> <i class="arg">dict</i></a></li>
<li><a href="#18"><b class="cmd">::page::pluginmgr::wtimeable</b></a></li>
<li><a href="#19"><b class="cmd">::page::pluginmgr::wtime</b></a></li>
<li><a href="#20"><b class="cmd">::page::pluginmgr::wgettime</b></a></li>
<li><a href="#21"><b class="cmd">::page::pluginmgr::whelp</b></a></li>
<li><a href="#22"><b class="cmd">::page::pluginmgr::wlabel</b></a></li>
<li><a href="#23"><b class="cmd">::page::pluginmgr::write</b> <i class="arg">chan</i> <i class="arg">data</i></a></li>
<li><a href="#24"><b class="cmd">::page::pluginmgr::transform</b> <i class="arg">name</i></a></li>
<li><a href="#25"><b class="cmd">::page::pluginmgr::tconfigure</b> <i class="arg">id</i> <i class="arg">dict</i></a></li>
<li><a href="#26"><b class="cmd">::page::pluginmgr::ttimeable</b> <i class="arg">id</i></a></li>
<li><a href="#27"><b class="cmd">::page::pluginmgr::ttime</b> <i class="arg">id</i></a></li>
<li><a href="#28"><b class="cmd">::page::pluginmgr::tgettime</b> <i class="arg">id</i></a></li>
<li><a href="#29"><b class="cmd">::page::pluginmgr::thelp</b> <i class="arg">id</i></a></li>
<li><a href="#30"><b class="cmd">::page::pluginmgr::tlabel</b> <i class="arg">id</i></a></li>
<li><a href="#31"><b class="cmd">::page::pluginmgr::transform_do</b> <i class="arg">id</i> <i class="arg">data</i></a></li>
<li><a href="#32"><b class="cmd">page_cdefinition</b></a></li>
<li><a href="#33"><b class="cmd">page_rfeature</b> <i class="arg">name</i></a></li>
<li><a href="#34"><b class="cmd">page_rtime</b></a></li>
<li><a href="#35"><b class="cmd">page_rgettime</b></a></li>
<li><a href="#36"><b class="cmd">page_rlabel</b></a></li>
<li><a href="#37"><b class="cmd">page_rhelp</b></a></li>
<li><a href="#38"><b class="cmd">page_roptions</b></a></li>
<li><a href="#39"><b class="cmd">page_rconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></li>
<li><a href="#40"><b class="cmd">page_rrun</b></a></li>
<li><a href="#41"><b class="cmd">page_read</b> <i class="arg">num</i></a></li>
<li><a href="#42"><b class="cmd">page_read_done</b></a></li>
<li><a href="#43"><b class="cmd">page_eof</b></a></li>
<li><a href="#44"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#45"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#46"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#47"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></li>
<li><a href="#48"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></li>
<li><a href="#49"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></li>
<li><a href="#50"><b class="cmd">page_wfeature</b></a></li>
<li><a href="#51"><b class="cmd">page_wtime</b></a></li>
<li><a href="#52"><b class="cmd">page_wgettime</b></a></li>
<li><a href="#53"><b class="cmd">page_wlabel</b></a></li>
<li><a href="#54"><b class="cmd">page_whelp</b></a></li>
<li><a href="#55"><b class="cmd">page_woptions</b></a></li>
<li><a href="#56"><b class="cmd">page_wconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></li>
<li><a href="#57"><b class="cmd">page_wrun</b> <i class="arg">chan</i> <i class="arg">data</i></a></li>
<li><a href="#58"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#59"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#60"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#61"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></li>
<li><a href="#62"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></li>
<li><a href="#63"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></li>
<li><a href="#64"><b class="cmd">page_tfeature</b></a></li>
<li><a href="#65"><b class="cmd">page_ttime</b></a></li>
<li><a href="#66"><b class="cmd">page_tgettime</b></a></li>
<li><a href="#67"><b class="cmd">page_tlabel</b></a></li>
<li><a href="#68"><b class="cmd">page_thelp</b></a></li>
<li><a href="#69"><b class="cmd">page_toptions</b></a></li>
<li><a href="#70"><b class="cmd">page_tconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></li>
<li><a href="#71"><b class="cmd">page_trun</b> <i class="arg">chan</i> <i class="arg">data</i></a></li>
<li><a href="#72"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#73"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#74"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#75"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></li>
<li><a href="#76"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></li>
<li><a href="#77"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
<p>This package provides the plugin manager central to the <b class="syscmd"><a href="../../apps/page.html">page</a></b>
application. It manages the various reader, writer, configuration, and
transformation plugins which actually process the text (read,
transform, and write).</p>
<p>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 <span class="sectref"><a href="#section7">PREDEFINED PLUGINS</a></span>, and not documented as regular
packages. It is expected that they follow the APIs specified in the
sections</p>
<ol class="enumerated">
<li><p><span class="sectref"><a href="#section3">CONFIG PLUGIN API</a></span></p></li>
<li><p><span class="sectref"><a href="#section4">READER PLUGIN API</a></span></p></li>
<li><p><span class="sectref"><a href="#section5">WRITER PLUGIN API</a></span></p></li>
<li><p><span class="sectref"><a href="#section6">TRANSFORM PLUGIN API</a></span></p></li>
</ol>
<p>as per their type.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">API</a></h2>
<dl class="definitions">
<dt><a name="1"><b class="cmd">::page::pluginmgr::reportvia</b> <i class="arg">cmd</i></a></dt>
<dd><p>This command defines the callback command used by
<b class="cmd">::page::pluginmgr::report</b> (see below) to report input errors and
warnings. The default is to write such reports to the standard error
channel.</p></dd>
<dt><a name="2"><b class="cmd">::page::pluginmgr::report</b> <i class="arg">level</i> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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
<b class="cmd">::page::pluginmgr::reportvia</b> (see above).</p>
<p>The arguments <i class="arg">level</i> and <i class="arg">text</i> specify both the importance
of the message, and the message itself. For the former see the package
<b class="package"><a href="../log/logger.html">logger</a></b> for the allowed values.</p>
<p>The optional argument <i class="arg">from</i> and <i class="arg">to</i> 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.</p></dd>
<dt><a name="3"><b class="cmd">::page::pluginmgr::log</b> <i class="arg">cmd</i></a></dt>
<dd><p>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.</p>
<p>Note: The <i class="arg">cmd</i> has to be created by the <b class="package"><a href="../log/logger.html">logger</a></b> package,
or follow the same API as such.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="4"><b class="cmd">::page::pluginmgr::configuration</b> <i class="arg">name</i></a></dt>
<dd><p>This command loads the named configuration plugin, retrieves the
options encoded in it, and then immediately unloads it again.</p>
<p>If the <i class="arg">name</i> 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.</p>
<p>See section <span class="sectref"><a href="#section3">CONFIG PLUGIN API</a></span> for the API expected of
configuration plugins.</p>
<p>The result of the command is the list of options retrieved.</p></dd>
<dt><a name="5"><b class="cmd">::page::pluginmgr::reader</b> <i class="arg">name</i></a></dt>
<dd><p>This command loads the named reader plugin and initializes it. The
result of the command is a list of options the plugin understands.</p>
<p>Only a single reader plugin can be loaded. Loading another reader
plugin causes the previously loaded reader plugin to be de-initialized
and unloaded.</p>
<p>See section <span class="sectref"><a href="#section4">READER PLUGIN API</a></span> for the API expected of
reader plugins.</p></dd>
<dt><a name="6"><b class="cmd">::page::pluginmgr::rconfigure</b> <i class="arg">dict</i></a></dt>
<dd><p>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.</p></dd>
<dt><a name="7"><b class="cmd">::page::pluginmgr::rtimeable</b></a></dt>
<dd><p>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 <b class="const">true</b> if the plugin can be timed, and <b class="const">false</b>
otherwise.</p></dd>
<dt><a name="8"><b class="cmd">::page::pluginmgr::rtime</b></a></dt>
<dd><p>This command activates the collection of timing statistics in the
loaded reader plugin.</p></dd>
<dt><a name="9"><b class="cmd">::page::pluginmgr::rgettime</b></a></dt>
<dd><p>This command retrieves the collected timing statistics of the loaded
reader plugin after it was executed.</p></dd>
<dt><a name="10"><b class="cmd">::page::pluginmgr::rhelp</b></a></dt>
<dd><p>This command retrieves the help string of the loaded reader
plugin. This is expected to be in <i class="term"><a href="../../../../index.html#key51">doctools</a></i> format.</p></dd>
<dt><a name="11"><b class="cmd">::page::pluginmgr::rlabel</b></a></dt>
<dd><p>This command retrieves the human-readable name of the loaded reader
plugin.</p></dd>
<dt><a name="12"><b class="cmd">::page::pluginmgr::read</b> <i class="arg">read</i> <i class="arg">eof</i> <span class="opt">?<i class="arg">complete</i>?</span></a></dt>
<dd><p>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 <i class="arg">read</i>, and <i class="arg">eof</i>. The
optional <i class="arg">done</i> can be used to intrecept when the plugin has
completed its processing. All arguments are command prefixes.</p>
<p>The plugin will invoke the various callbacks in the following
situations:</p>
<dl class="definitions">
<dt><a name="13"><i class="arg">read</i> <i class="arg">num</i></a></dt>
<dd><p>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.</p></dd>
<dt><a name="14"><i class="arg">eof</i></a></dt>
<dd><p>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, <b class="const">true</b> when
the input has hit EOF, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="15"><i class="arg">done</i></a></dt>
<dd><p>is invoked when the plugin has completed the processing of the input.</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::page::pluginmgr::writer</b> <i class="arg">name</i></a></dt>
<dd><p>This command loads the named writer plugin and initializes it. The
result of the command is a list of options the plugin understands.</p>
<p>Only a single reader plugin can be loaded. Loading another reader
plugin causes the previously loaded reader plugin to be de-initialized
and unloaded.</p>
<p>See section <span class="sectref"><a href="#section5">WRITER PLUGIN API</a></span> for the API expected of
writer plugins.</p></dd>
<dt><a name="17"><b class="cmd">::page::pluginmgr::wconfigure</b> <i class="arg">dict</i></a></dt>
<dd><p>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.</p></dd>
<dt><a name="18"><b class="cmd">::page::pluginmgr::wtimeable</b></a></dt>
<dd><p>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 <b class="const">true</b> if the plugin can be timed, and <b class="const">false</b>
otherwise.</p></dd>
<dt><a name="19"><b class="cmd">::page::pluginmgr::wtime</b></a></dt>
<dd><p>This command activates the collection of timing statistics in the
loaded writer plugin.</p></dd>
<dt><a name="20"><b class="cmd">::page::pluginmgr::wgettime</b></a></dt>
<dd><p>This command retrieves the collected timing statistics of the loaded
writer plugin after it was executed.</p></dd>
<dt><a name="21"><b class="cmd">::page::pluginmgr::whelp</b></a></dt>
<dd><p>This command retrieves the help string of the loaded writer
plugin. This is expected to be in <i class="term"><a href="../../../../index.html#key51">doctools</a></i> format.</p></dd>
<dt><a name="22"><b class="cmd">::page::pluginmgr::wlabel</b></a></dt>
<dd><p>This command retrieves the human-readable name of the loaded writer
plugin.</p></dd>
<dt><a name="23"><b class="cmd">::page::pluginmgr::write</b> <i class="arg">chan</i> <i class="arg">data</i></a></dt>
<dd><p>The loaded writer plugin is invoked to generate the output. It is
given the <i class="arg">data</i> to generate the outpout from, and the Tcl handle
<i class="arg">chan</i> of the channel to write the generated output to. The
command returns th empty string as its result.</p></dd>
<dt><a name="24"><b class="cmd">::page::pluginmgr::transform</b> <i class="arg">name</i></a></dt>
<dd><p>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.</p>
<p>Multiple transformations plugins can be loaded and are identified by
handles.</p>
<p>See section <span class="sectref"><a href="#section6">TRANSFORM PLUGIN API</a></span> for the API expected of
transformation plugins.</p></dd>
<dt><a name="25"><b class="cmd">::page::pluginmgr::tconfigure</b> <i class="arg">id</i> <i class="arg">dict</i></a></dt>
<dd><p>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.</p></dd>
<dt><a name="26"><b class="cmd">::page::pluginmgr::ttimeable</b> <i class="arg">id</i></a></dt>
<dd><p>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 <b class="const">true</b> if the plugin can be timed, and
<b class="const">false</b> otherwise.</p></dd>
<dt><a name="27"><b class="cmd">::page::pluginmgr::ttime</b> <i class="arg">id</i></a></dt>
<dd><p>This command activates the collection of timing statistics in the
identified transformation plugin.</p></dd>
<dt><a name="28"><b class="cmd">::page::pluginmgr::tgettime</b> <i class="arg">id</i></a></dt>
<dd><p>This command retrieves the collected timing statistics of the
identified transformation plugin after it was executed.</p></dd>
<dt><a name="29"><b class="cmd">::page::pluginmgr::thelp</b> <i class="arg">id</i></a></dt>
<dd><p>This command retrieves the help string of the identified
transformation plugin. This is expected to be in <i class="term"><a href="../../../../index.html#key51">doctools</a></i>
format.</p></dd>
<dt><a name="30"><b class="cmd">::page::pluginmgr::tlabel</b> <i class="arg">id</i></a></dt>
<dd><p>This command retrieves the human-readable name of the identified
transformation plugin.</p></dd>
<dt><a name="31"><b class="cmd">::page::pluginmgr::transform_do</b> <i class="arg">id</i> <i class="arg">data</i></a></dt>
<dd><p>The identified transformation plugin is invoked to process the
specified <i class="arg">data</i>. The result of the plugin is returned as the
result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="section"><h2><a name="section3">CONFIG PLUGIN API</a></h2>
<p>Configuration plugins are expected to provide a single command,
described below.</p>
<dl class="definitions">
<dt><a name="32"><b class="cmd">page_cdefinition</b></a></dt>
<dd><p>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.</p></dd>
</dl>
<p>Configuration plugins do not expect the environment to provide any
special commands.</p>
<p>It is expected that a configuration plugin <b class="const">FOO</b> is implemented
by the package <b class="package">page::config::<b class="const">FOO</b></b>.</p>
<p>Configuration plugins are loaded, executed, and unloaded in one step,
they are not kept in memory. The command for doing this is
<b class="cmd">::page::pluginmgr::configuration</b>.</p>
</div>
<div id="section4" class="section"><h2><a name="section4">READER PLUGIN API</a></h2>
<p>Reader plugins are expected to provide the following commands,
described below.</p>
<dl class="definitions">
<dt><a name="33"><b class="cmd">page_rfeature</b> <i class="arg">name</i></a></dt>
<dd><p>This command takes a feature <i class="arg">name</i> and returns a boolean flag
indicating whether the feature is supported by the plugin, or not.
The result has to be <b class="const">true</b> if the feature is supported, and
<b class="const">false</b> otherwise.</p>
<p>See section <span class="sectref"><a href="#section8">FEATURES</a></span> for the possible features the plugin
manager will ask for.</p></dd>
<dt><a name="34"><b class="cmd">page_rtime</b></a></dt>
<dd><p>This command is invoked to activate the collection of timing
statistics.</p></dd>
<dt><a name="35"><b class="cmd">page_rgettime</b></a></dt>
<dd><p>This command is invoked to retrieve the collected timing statistics.</p></dd>
<dt><a name="36"><b class="cmd">page_rlabel</b></a></dt>
<dd><p>This command is invoked to retrieve a human-readable label for the
plugin.</p></dd>
<dt><a name="37"><b class="cmd">page_rhelp</b></a></dt>
<dd><p>This command is invoked to retrieve a help text for plugin. The text
is expected to be in <i class="term"><a href="../../../../index.html#key51">doctools</a></i> format.</p></dd>
<dt><a name="38"><b class="cmd">page_roptions</b></a></dt>
<dd><p>This command is invoked to retrieve the options understood by the
plugin.</p></dd>
<dt><a name="39"><b class="cmd">page_rconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></dt>
<dd><p>This command is invoked to reconfigure the plugin, specifically the
given <i class="arg">option</i> is set to the new <i class="arg">value</i>.</p></dd>
<dt><a name="40"><b class="cmd">page_rrun</b></a></dt>
<dd><p>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.</p></dd>
</dl>
<p>Reader plugins expect the environment to provide the following special
commands.</p>
<dl class="definitions">
<dt><a name="41"><b class="cmd">page_read</b> <i class="arg">num</i></a></dt>
<dd><p>This command is invoked to read <i class="arg">num</i> characters/bytes from the
input. Its result has to be read characters/bytes.</p></dd>
<dt><a name="42"><b class="cmd">page_read_done</b></a></dt>
<dd><p>This command is invoked to signal that the plugin has completed the
processing of the input.</p></dd>
<dt><a name="43"><b class="cmd">page_eof</b></a></dt>
<dd><p>This command is invoked to check if the input stream has reached its
end. Its result has to be a boolean flag, <b class="const">true</b> when the input
has reached the end, <b class="const">false</b> otherwise.</p></dd>
<dt><a name="44"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="45"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="46"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="47"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report some internal information.</p></dd>
<dt><a name="48"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal warning.</p></dd>
<dt><a name="49"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal error.</p></dd>
</dl>
<p>It is expected that a reader plugin <b class="const">FOO</b> is implemented
by the package <b class="package">page::reader::<b class="const">FOO</b></b>.</p>
<p>Reader plugins are loaded by the command
<b class="cmd">::page::pluginmgr::reader</b>. At most one reader plugin can be kept
in memory.</p>
</div>
<div id="section5" class="section"><h2><a name="section5">WRITER PLUGIN API</a></h2>
<p>Writer plugins are expected to provide the following commands,
described below.</p>
<dl class="definitions">
<dt><a name="50"><b class="cmd">page_wfeature</b></a></dt>
<dd><p>This command takes a feature <i class="arg">name</i> and returns a boolean flag
indicating whether the feature is supported by the plugin, or not.
The result has to be <b class="const">true</b> if the feature is supported, and
<b class="const">false</b> otherwise.</p>
<p>See section <span class="sectref"><a href="#section8">FEATURES</a></span> for the possible features the plugin
manager will ask for.</p></dd>
<dt><a name="51"><b class="cmd">page_wtime</b></a></dt>
<dd><p>This command is invoked to activate the collection of timing
statistics.</p></dd>
<dt><a name="52"><b class="cmd">page_wgettime</b></a></dt>
<dd><p>This command is invoked to retrieve the collected timing statistics.</p></dd>
<dt><a name="53"><b class="cmd">page_wlabel</b></a></dt>
<dd><p>This command is invoked to retrieve a human-readable label for the
plugin.</p></dd>
<dt><a name="54"><b class="cmd">page_whelp</b></a></dt>
<dd><p>This command is invoked to retrieve a help text for plugin. The text
is expected to be in <i class="term"><a href="../../../../index.html#key51">doctools</a></i> format.</p></dd>
<dt><a name="55"><b class="cmd">page_woptions</b></a></dt>
<dd><p>This command is invoked to retrieve the options understood by the
plugin.</p></dd>
<dt><a name="56"><b class="cmd">page_wconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></dt>
<dd><p>This command is invoked to reconfigure the plugin, specifically the
given <i class="arg">option</i> is set to the new <i class="arg">value</i>.</p></dd>
<dt><a name="57"><b class="cmd">page_wrun</b> <i class="arg">chan</i> <i class="arg">data</i></a></dt>
<dd><p>This command is invoked to process the specified <i class="arg">data</i> and write
it to the output stream <i class="arg">chan</i>. The latter is a Tcl channel handle
opened for writing. The result of the command is the empty string.</p></dd>
</dl>
<p>Writer plugins expect the environment to provide the following special
commands.</p>
<dl class="definitions">
<dt><a name="58"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="59"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="60"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="61"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report some internal information.</p></dd>
<dt><a name="62"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal warning.</p></dd>
<dt><a name="63"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal error.</p></dd>
</dl>
<p>It is expected that a writer plugin <b class="const">FOO</b> is implemented
by the package <b class="package">page::writer::<b class="const">FOO</b></b>.</p>
<p>Writer plugins are loaded by the command
<b class="cmd">::page::pluginmgr::writer</b>. At most one writer plugin can be kept
in memory.</p>
</div>
<div id="section6" class="section"><h2><a name="section6">TRANSFORM PLUGIN API</a></h2>
<p>page::transform::*
Transformation plugins are expected to provide the following commands,
described below.</p>
<dl class="definitions">
<dt><a name="64"><b class="cmd">page_tfeature</b></a></dt>
<dd><p>This command takes a feature <i class="arg">name</i> and returns a boolean flag
indicating whether the feature is supported by the plugin, or not.
The result has to be <b class="const">true</b> if the feature is supported, and
<b class="const">false</b> otherwise.</p>
<p>See section <span class="sectref"><a href="#section8">FEATURES</a></span> for the possible features the plugin
manager will ask for.</p></dd>
<dt><a name="65"><b class="cmd">page_ttime</b></a></dt>
<dd><p>This command is invoked to activate the collection of timing
statistics.</p></dd>
<dt><a name="66"><b class="cmd">page_tgettime</b></a></dt>
<dd><p>This command is invoked to retrieve the collected timing statistics.</p></dd>
<dt><a name="67"><b class="cmd">page_tlabel</b></a></dt>
<dd><p>This command is invoked to retrieve a human-readable label for the
plugin.</p></dd>
<dt><a name="68"><b class="cmd">page_thelp</b></a></dt>
<dd><p>This command is invoked to retrieve a help text for plugin. The text
is expected to be in <i class="term"><a href="../../../../index.html#key51">doctools</a></i> format.</p></dd>
<dt><a name="69"><b class="cmd">page_toptions</b></a></dt>
<dd><p>This command is invoked to retrieve the options understood by the
plugin.</p></dd>
<dt><a name="70"><b class="cmd">page_tconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></dt>
<dd><p>This command is invoked to reconfigure the plugin, specifically the
given <i class="arg">option</i> is set to the new <i class="arg">value</i>.</p></dd>
<dt><a name="71"><b class="cmd">page_trun</b> <i class="arg">chan</i> <i class="arg">data</i></a></dt>
<dd><p>This command is invoked to process the specified <i class="arg">data</i> and write
it to the output stream <i class="arg">chan</i>. The latter is a Tcl channel handle
opened for writing. The result of the command is the empty string.</p></dd>
</dl>
<p>Transformation plugins expect the environment to provide the following
special commands.</p>
<dl class="definitions">
<dt><a name="72"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="73"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="74"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="75"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report some internal information.</p></dd>
<dt><a name="76"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal warning.</p></dd>
<dt><a name="77"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal error.</p></dd>
</dl>
<p>It is expected that a transformation plugin <b class="const">FOO</b> is implemented
by the package <b class="package">page::transform::<b class="const">FOO</b></b>.</p>
<p>Transformation plugins are loaded by the command
<b class="cmd">::page::pluginmgr::transform</b>. More than one transformation
plugin can be kept in memory.</p>
</div>
<div id="section7" class="section"><h2><a name="section7">PREDEFINED PLUGINS</a></h2>
<p>The following predefined plugins are known, i.e. provided by the page
module.</p>
<dl class="definitions">
<dt>Configuration</dt>
<dd><dl class="definitions">
<dt>peg</dt>
<dd><p>Returns a set of options to configure the <b class="syscmd"><a href="../../apps/page.html">page</a></b> application
for the processing of a PEG grammar and the generation of ME code. See
the packages <b class="package">grammar_peg</b>, <b class="package">grammar_me</b> and relations
for more details.</p></dd>
</dl></dd>
<dt>Reader</dt>
<dd><dl class="definitions">
<dt>hb</dt>
<dd><p>Expects a so-called <i class="term">half-baked PEG container</i> as input and
returns the equivalent abstract syntax tree. See the writer plugin
<i class="term">hb</i> for the plugin generating this type of input.</p></dd>
<dt>lemon</dt>
<dd><p>Expects a grammar specification as understood by Richar Hipp's LEMON
parser generator and returns an abstract syntax tree for it.</p></dd>
<dt>peg</dt>
<dd><p>Expects a grammar specification in the form of a parsing expression
grammar (PEG) and returns an abstract syntax tree for it.</p></dd>
<dt>ser</dt>
<dd><p>Expect the serialized form of a parsing expression grammar as
generated by the package <b class="package"><a href="../grammar_peg/peg.html">grammar::peg</a></b> as input, converts it
into an equivalent abstract syntax tree and returns that.</p></dd>
<dt>treeser</dt>
<dd><p>Expects the serialized form of a tree as generated by the package
<b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b> as input and returns it, after validation.</p></dd>
</dl></dd>
<dt>Writer</dt>
<dd><dl class="definitions">
<dt>hb</dt>
<dd><p>Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out in the form of a so-called
<i class="term">half-baked PEG container</i>.</p></dd>
<dt>identity</dt>
<dd><p>Takes any input and writes it as is.</p></dd>
<dt>mecpu</dt>
<dd><p>Expects symbolic assembler code for the MatchEngine CPU (See the
package <b class="package"><a href="../grammar_me/me_cpu.html">grammar::me::cpu</a></b> and relatives) and writes it out as
Tcl code for a parser.</p></dd>
<dt>me</dt>
<dd><p>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 <b class="package">grammar::me</b> and relatives) which parses input in
that grammar.</p></dd>
<dt>null</dt>
<dd><p>Takes any input and writes nothing. The logical equivalent of
/dev/null.</p></dd>
<dt>peg</dt>
<dd><p>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 <i class="term">peg</i>.</p></dd>
<dt>ser</dt>
<dd><p>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 <i class="term">ser</i>.</p></dd>
<dt>tpc</dt>
<dd><p>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 <b class="package"><a href="../grammar_peg/peg.html">grammar::peg</a></b>.</p></dd>
<dt>tree</dt>
<dd><p>Takes any serialized tree (per package <b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b>) as
input and writes it out in a generic indented format.</p></dd>
</dl></dd>
<dt>Transformation</dt>
<dd><dl class="definitions">
<dt>mecpu</dt>
<dd><p>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 <b class="package"><a href="../grammar_me/me_cpu.html">grammar::me::cpu</a></b>
and relatives).</p></dd>
<dt>reachable</dt>
<dd><p>Takes an abstract syntax tree for a parsing expression grammer as
input, performs a reachability analysis, and returns the modified and
annotated tree.</p></dd>
<dt>realizable</dt>
<dd><p>Takes an abstract syntax tree for a parsing expression grammer as
input, performs an analysis of realizability, and returns the modified
and annotated tree.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section8" class="section"><h2><a name="section8">FEATURES</a></h2>
<p>The plugin manager currently checks the plugins for only one feature,
<b class="const">timeable</b>. A plugin supporting this feature is assumed to be
able to collect timing statistics on request.</p>
</div>
<div id="section9" class="section"><h2><a name="section9">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>page</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
</div>
<div id="keywords" class="section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#key189">page</a>, <a href="../../../../index.html#key187">parser generator</a>, <a href="../../../../index.html#key190">text processing</a></p>
</div>
<div id="category" class="section"><h2><a name="category">Category</a></h2>
<p>Page Parser Generator</p>
</div>
<div id="copyright" class="section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div></body></html>
