1page_pluginmgr(n) Parser generator tools page_pluginmgr(n)
2______________________________________________________________________________
6
8 page_pluginmgr - page plugin manager
9
11 package require page::pluginmgr ?0.2?
12 package require fileutil
14 ::page::pluginmgr::reportvia cmd
16 ::page::pluginmgr::report level text ?from ?to??
18 ::page::pluginmgr::log cmd
20 ::page::pluginmgr::configuration name
22 ::page::pluginmgr::reader name
24 ::page::pluginmgr::rconfigure dict
26 ::page::pluginmgr::rtimeable
28 ::page::pluginmgr::rtime
30 ::page::pluginmgr::rgettime
32 ::page::pluginmgr::rhelp
34 ::page::pluginmgr::rlabel
36 ::page::pluginmgr::read read eof ?complete?
38 read num
40 eof
42 done
44 ::page::pluginmgr::writer name
46 ::page::pluginmgr::wconfigure dict
48 ::page::pluginmgr::wtimeable
50 ::page::pluginmgr::wtime
52 ::page::pluginmgr::wgettime
54 ::page::pluginmgr::whelp
56 ::page::pluginmgr::wlabel
58 ::page::pluginmgr::write chan data
60 ::page::pluginmgr::transform name
62 ::page::pluginmgr::tconfigure id dict
64 ::page::pluginmgr::ttimeable id
66 ::page::pluginmgr::ttime id
68 ::page::pluginmgr::tgettime id
70 ::page::pluginmgr::thelp id
72 ::page::pluginmgr::tlabel id
74 ::page::pluginmgr::transform_do id data
76 page_cdefinition
78 page_rfeature name
80 page_rtime
82 page_rgettime
84 page_rlabel
86 page_rhelp
88 page_roptions
90 page_rconfigure option value
92 page_rrun
94 page_read num
96 page_read_done
98 page_eof
100 page_info text ?from ?to??
102 page_warning text ?from ?to??
104 page_error text ?from ?to??
106 page_log_info text
108 page_log_warning text
110 page_log_error text
112 page_wfeature
114 page_wtime
116 page_wgettime
118 page_wlabel
120 page_whelp
122 page_woptions
124 page_wconfigure option value
126 page_wrun chan data
128 page_info text ?from ?to??
130 page_warning text ?from ?to??
132 page_error text ?from ?to??
134 page_log_info text
136 page_log_warning text
138 page_log_error text
140 page_tfeature
142 page_ttime
144 page_tgettime
146 page_tlabel
148 page_thelp
150 page_toptions
152 page_tconfigure option value
154 page_trun chan data
156 page_info text ?from ?to??
158 page_warning text ?from ?to??
160 page_error text ?from ?to??
162 page_log_info text
164 page_log_warning text
166 page_log_error text
168_________________________________________________________________
170
172 This package provides the plugin manager central to the page applica‐
173 tion. It manages the various reader, writer, configuration, and trans‐
174 formation plugins which actually process the text (read, transform, and
175 write).
176 All plugins are loaded into slave interpreters specially prepared for
178 them. While implemented using packages they need this special environ‐
179 ment and are not usable in a plain interpreter, like tclsh. Because of
180 that they are only described in general terms in section PREDEFINED
181 PLUGINS, and not documented as regular packages. It is expected that
182 they follow the APIs specified in the sections
183 [1] CONFIG PLUGIN API
185 [2] READER PLUGIN API
187 [3] WRITER PLUGIN API
189 [4] TRANSFORM PLUGIN API
191 as per their type.
193
195 ::page::pluginmgr::reportvia cmd
196 This command defines the callback command used by ::page::plug‐
197 inmgr::report (see below) to report input errors and warnings.
198 The default is to write such reports to the standard error chan‐
199 nel.
200 ::page::pluginmgr::report level text ?from ?to??
202 This command is used to report input errors and warnings. By
203 default such reports are written to the standard error. This can
204 be changed by setting a user-specific callback command with
205 ::page::pluginmgr::reportvia (see above).
206 The arguments level and text specify both the importance of the
208 message, and the message itself. For the former see the package
209 logger for the allowed values.
210 The optional argument from and to can be used by the caller to
212 indicate the location (or range) in the input where the reported
213 problem occured. Each is a list containing two elements, the
214 line and the column in the input, in this order.
215 ::page::pluginmgr::log cmd
217 This command defines a log callback command to be used by loaded
218 plugins for the reporting of internal errors, warnings, and gen‐
219 eral information. Specifying the empty string as callback dis‐
220 ables logging.
221 Note: The cmd has to be created by the logger package, or follow
223 the same API as such.
224 The command returns the empty string as its result.
226 ::page::pluginmgr::configuration name
228 This command loads the named configuration plugin, retrieves the
229 options encoded in it, and then immediately unloads it again.
230 If the name is the path to a file, then this files will be tried
232 to be loaded as a plugin first, and, if that fails, opened and
233 its contents read as a list of options and their arguments, sep‐
234 arated by spaces, tabs and newlines, possibly quotes with single
235 and double quotes.
236 See section CONFIG PLUGIN API for the API expected of configura‐
238 tion plugins.
239 The result of the command is the list of options retrieved.
241 ::page::pluginmgr::reader name
243 This command loads the named reader plugin and initializes it.
244 The result of the command is a list of options the plugin under‐
245 stands.
246 Only a single reader plugin can be loaded. Loading another
248 reader plugin causes the previously loaded reader plugin to be
249 de-initialized and unloaded.
250 See section READER PLUGIN API for the API expected of reader
252 plugins.
253 ::page::pluginmgr::rconfigure dict
255 This commands configures the loaded reader plugin. The options
256 and their values are provided as a Tcl dictionary. The result of
257 the command is the empty string.
258 ::page::pluginmgr::rtimeable
260 This commands checks if the loaded reader plugin is able to col‐
261 lect timing statistics. The result of the command is a boolean
262 flag. The result is true if the plugin can be timed, and false
263 otherwise.
264 ::page::pluginmgr::rtime
266 This command activates the collection of timing statistics in
267 the loaded reader plugin.
268 ::page::pluginmgr::rgettime
270 This command retrieves the collected timing statistics of the
271 loaded reader plugin after it was executed.
272 ::page::pluginmgr::rhelp
274 This command retrieves the help string of the loaded reader
275 plugin. This is expected to be in doctools format.
276 ::page::pluginmgr::rlabel
278 This command retrieves the human-readable name of the loaded
279 reader plugin.
280 ::page::pluginmgr::read read eof ?complete?
282 This command invokes the loaded reader plugin to process the
283 input, and returns the results of the plugin as its own result.
284 The input is accessible through the callback commands read, and
285 eof. The optional done can be used to intrecept when the plugin
286 has completed its processing. All arguments are command pre‐
287 fixes.
288 The plugin will invoke the various callbacks in the following
290 situations:
291 read num
293 is invoked whenever input to process is needed, with the
294 number of characters/bytes it asks for. The result is
295 expected to be the input the plugin is in need of.
296 eof is invoked by the plugin to check if the input has
298 reached the of the stream. The result is expected to be a
299 boolean flag, true when the input has hit EOF, and false
300 otherwise.
301 done is invoked when the plugin has completed the processing
303 of the input.
304 ::page::pluginmgr::writer name
306 This command loads the named writer plugin and initializes it.
307 The result of the command is a list of options the plugin under‐
308 stands.
309 Only a single reader plugin can be loaded. Loading another
311 reader plugin causes the previously loaded reader plugin to be
312 de-initialized and unloaded.
313 See section WRITER PLUGIN API for the API expected of writer
315 plugins.
316 ::page::pluginmgr::wconfigure dict
318 This commands configures the loaded writer plugin. The options
319 and their values are provided as a Tcl dictionary. The result of
320 the command is the empty string.
321 ::page::pluginmgr::wtimeable
323 This commands checks if the loaded writer plugin is able to mea‐
324 sure execution times. The result of the command is a boolean
325 flag. The result is true if the plugin can be timed, and false
326 otherwise.
327 ::page::pluginmgr::wtime
329 This command activates the collection of timing statistics in
330 the loaded writer plugin.
331 ::page::pluginmgr::wgettime
333 This command retrieves the collected timing statistics of the
334 loaded writer plugin after it was executed.
335 ::page::pluginmgr::whelp
337 This command retrieves the help string of the loaded writer
338 plugin. This is expected to be in doctools format.
339 ::page::pluginmgr::wlabel
341 This command retrieves the human-readable name of the loaded
342 writer plugin.
343 ::page::pluginmgr::write chan data
345 The loaded writer plugin is invoked to generate the output. It
346 is given the data to generate the outpout from, and the Tcl han‐
347 dle chan of the channel to write the generated output to. The
348 command returns th empty string as its result.
349 ::page::pluginmgr::transform name
351 This command loads the named transformation plugin and initial‐
352 izes it. The result of the command is a 2-element list contain‐
353 ing the plugin id and a list of options the plugin understands,
354 in this order.
355 Multiple transformations plugins can be loaded and are identi‐
357 fied by handles.
358 See section TRANSFORM PLUGIN API for the API expected of trans‐
360 formation plugins.
361 ::page::pluginmgr::tconfigure id dict
363 This commands configures the identified transformation plugin.
364 The options and their values are provided as a Tcl dictionary.
365 The result of the command is the empty string.
366 ::page::pluginmgr::ttimeable id
368 This commands checks if the identified transformation plugin is
369 able to collect timing statistics. The result of the command is
370 a boolean flag. The result is true if the plugin can be timed,
371 and false otherwise.
372 ::page::pluginmgr::ttime id
374 This command activates the collection of timing statistics in
375 the identified transformation plugin.
376 ::page::pluginmgr::tgettime id
378 This command retrieves the collected timing statistics of the
379 identified transformation plugin after it was executed.
380 ::page::pluginmgr::thelp id
382 This command retrieves the help string of the identified trans‐
383 formation plugin. This is expected to be in doctools format.
384 ::page::pluginmgr::tlabel id
386 This command retrieves the human-readable name of the identified
387 transformation plugin.
388 ::page::pluginmgr::transform_do id data
390 The identified transformation plugin is invoked to process the
391 specified data. The result of the plugin is returned as the
392 result of the command.
393
395 Configuration plugins are expected to provide a single command,
396 described below.
397 page_cdefinition
399 This command of a configuration plugin is called by the plugin
400 manager to execute it. Its result has to be a list of options
401 and values to process.
402 Configuration plugins do not expect the environment to provide any spe‐
404 cial commands.
405 It is expected that a configuration plugin FOO is implemented by the
407 package page::config::FOO.
408 Configuration plugins are loaded, executed, and unloaded in one step,
410 they are not kept in memory. The command for doing this is
411 ::page::pluginmgr::configuration.
412
414 Reader plugins are expected to provide the following commands,
415 described below.
416 page_rfeature name
418 This command takes a feature name and returns a boolean flag
419 indicating whether the feature is supported by the plugin, or
420 not. The result has to be true if the feature is supported, and
421 false otherwise.
422 See section FEATURES for the possible features the plugin man‐
424 ager will ask for.
425 page_rtime
427 This command is invoked to activate the collection of timing
428 statistics.
429 page_rgettime
431 This command is invoked to retrieve the collected timing statis‐
432 tics.
433 page_rlabel
435 This command is invoked to retrieve a human-readable label for
436 the plugin.
437 page_rhelp
439 This command is invoked to retrieve a help text for plugin. The
440 text is expected to be in doctools format.
441 page_roptions
443 This command is invoked to retrieve the options understood by
444 the plugin.
445 page_rconfigure option value
447 This command is invoked to reconfigure the plugin, specifically
448 the given option is set to the new value.
449 page_rrun
451 This command is invoked to process the input stream per the cur‐
452 rent plugin configuration. The result of the command is the
453 result of the processing.
454 Reader plugins expect the environment to provide the following special
456 commands.
457 page_read num
459 This command is invoked to read num characters/bytes from the
460 input. Its result has to be read characters/bytes.
461 page_read_done
463 This command is invoked to signal that the plugin has completed
464 the processing of the input.
465 page_eof
467 This command is invoked to check if the input stream has reached
468 its end. Its result has to be a boolean flag, true when the
469 input has reached the end, false otherwise.
470 page_info text ?from ?to??
472 Invoked to report some information to the user. May indicate a
473 location or range in the input. Each piece of location data, if
474 provided, is a 2-element list containing line and column num‐
475 bers.
476 page_warning text ?from ?to??
478 Invoked to report a warning to the user. May indicate a location
479 or range in the input. Each piece of location data, if provided,
480 is a 2-element list containing line and column numbers.
481 page_error text ?from ?to??
483 Invoked to report an error to the user. May indicate a location
484 or range in the input. Each piece of location data, if provided,
485 is a 2-element list containing line and column numbers.
486 page_log_info text
488 Invoked to report some internal information.
489 page_log_warning text
491 Invoked to report an internal warning.
492 page_log_error text
494 Invoked to report an internal error.
495 It is expected that a reader plugin FOO is implemented by the package
497 page::reader::FOO.
498 Reader plugins are loaded by the command ::page::pluginmgr::reader. At
500 most one reader plugin can be kept in memory.
501
503 Writer plugins are expected to provide the following commands,
504 described below.
505 page_wfeature
507 This command takes a feature name and returns a boolean flag
508 indicating whether the feature is supported by the plugin, or
509 not. The result has to be true if the feature is supported, and
510 false otherwise.
511 See section FEATURES for the possible features the plugin man‐
513 ager will ask for.
514 page_wtime
516 This command is invoked to activate the collection of timing
517 statistics.
518 page_wgettime
520 This command is invoked to retrieve the collected timing statis‐
521 tics.
522 page_wlabel
524 This command is invoked to retrieve a human-readable label for
525 the plugin.
526 page_whelp
528 This command is invoked to retrieve a help text for plugin. The
529 text is expected to be in doctools format.
530 page_woptions
532 This command is invoked to retrieve the options understood by
533 the plugin.
534 page_wconfigure option value
536 This command is invoked to reconfigure the plugin, specifically
537 the given option is set to the new value.
538 page_wrun chan data
540 This command is invoked to process the specified data and write
541 it to the output stream chan. The latter is a Tcl channel handle
542 opened for writing. The result of the command is the empty
543 string.
544 Writer plugins expect the environment to provide the following special
546 commands.
547 page_info text ?from ?to??
549 Invoked to report some information to the user. May indicate a
550 location or range in the input. Each piece of location data, if
551 provided, is a 2-element list containing line and column num‐
552 bers.
553 page_warning text ?from ?to??
555 Invoked to report a warning to the user. May indicate a location
556 or range in the input. Each piece of location data, if provided,
557 is a 2-element list containing line and column numbers.
558 page_error text ?from ?to??
560 Invoked to report an error to the user. May indicate a location
561 or range in the input. Each piece of location data, if provided,
562 is a 2-element list containing line and column numbers.
563 page_log_info text
565 Invoked to report some internal information.
566 page_log_warning text
568 Invoked to report an internal warning.
569 page_log_error text
571 Invoked to report an internal error.
572 It is expected that a writer plugin FOO is implemented by the package
574 page::writer::FOO.
575 Writer plugins are loaded by the command ::page::pluginmgr::writer. At
577 most one writer plugin can be kept in memory.
578
580 Transformation plugins are expected to provide the following commands,
581 described below.
582 page_tfeature
584 This command takes a feature name and returns a boolean flag
585 indicating whether the feature is supported by the plugin, or
586 not. The result has to be true if the feature is supported, and
587 false otherwise.
588 See section FEATURES for the possible features the plugin man‐
590 ager will ask for.
591 page_ttime
593 This command is invoked to activate the collection of timing
594 statistics.
595 page_tgettime
597 This command is invoked to retrieve the collected timing statis‐
598 tics.
599 page_tlabel
601 This command is invoked to retrieve a human-readable label for
602 the plugin.
603 page_thelp
605 This command is invoked to retrieve a help text for plugin. The
606 text is expected to be in doctools format.
607 page_toptions
609 This command is invoked to retrieve the options understood by
610 the plugin.
611 page_tconfigure option value
613 This command is invoked to reconfigure the plugin, specifically
614 the given option is set to the new value.
615 page_trun chan data
617 This command is invoked to process the specified data and write
618 it to the output stream chan. The latter is a Tcl channel handle
619 opened for writing. The result of the command is the empty
620 string.
621 Transformation plugins expect the environment to provide the following
623 special commands.
624 page_info text ?from ?to??
626 Invoked to report some information to the user. May indicate a
627 location or range in the input. Each piece of location data, if
628 provided, is a 2-element list containing line and column num‐
629 bers.
630 page_warning text ?from ?to??
632 Invoked to report a warning to the user. May indicate a location
633 or range in the input. Each piece of location data, if provided,
634 is a 2-element list containing line and column numbers.
635 page_error text ?from ?to??
637 Invoked to report an error to the user. May indicate a location
638 or range in the input. Each piece of location data, if provided,
639 is a 2-element list containing line and column numbers.
640 page_log_info text
642 Invoked to report some internal information.
643 page_log_warning text
645 Invoked to report an internal warning.
646 page_log_error text
648 Invoked to report an internal error.
649 It is expected that a transformation plugin FOO is implemented by the
651 package page::transform::FOO.
652 Transformation plugins are loaded by the command ::page::plugin‐
654 mgr::transform. More than one transformation plugin can be kept in mem‐
655 ory.
656
658 The following predefined plugins are known, i.e. provided by the page
659 module.
660 Configuration
662 peg Returns a set of options to configure the page applica‐
664 tion for the processing of a PEG grammar and the genera‐
665 tion of ME code. See the packages grammar_peg, grammar_me
666 and relations for more details.
667 Reader
669 hb Expects a so-called half-baked PEG container as input and
671 returns the equivalent abstract syntax tree. See the
672 writer plugin hb for the plugin generating this type of
673 input.
674 lemon Expects a grammar specification as understood by Richar
676 Hipp's LEMON parser generator and returns an abstract
677 syntax tree for it.
678 peg Expects a grammar specification in the form of a parsing
680 expression grammar (PEG) and returns an abstract syntax
681 tree for it.
682 ser Expect the serialized form of a parsing expression gram‐
684 mar as generated by the package grammar::peg as input,
685 converts it into an equivalent abstract syntax tree and
686 returns that.
687 treeser
689 Expects the serialized form of a tree as generated by the
690 package struct::tree as input and returns it, after vali‐
691 dation.
692 Writer
694 hb Expects an abstract syntax tree for a parsing expression
696 grammar as input and writes it out in the form of a so-
697 called half-baked PEG container.
698 identity
700 Takes any input and writes it as is.
701 mecpu Expects symbolic assembler code for the MatchEngine CPU
703 (See the package grammar::me::cpu and relatives) and
704 writes it out as Tcl code for a parser.
705 me Expects an abstract syntax tree for a parsing expression
707 grammar as input and writes it out as Tcl code for the
708 MatchEngine (See the package grammar::me and relatives)
709 which parses input in that grammar.
710 null Takes any input and writes nothing. The logical equiva‐
712 lent of /dev/null.
713 peg Expects an abstract syntax tree for a parsing expression
715 grammar as input and writes it out in the form of a
716 canonical PEG which can be read by the reader plugin peg.
717 ser Expects an abstract syntax tree for a parsing expression
719 grammar as input and writes it out as a serialized PEG
720 container which can be read by the reader plugin ser.
721 tpc Expects an abstract syntax tree for a parsing expression
723 grammar as input and writes it out as Tcl code initializ‐
724 ing a PEG container as provided by the package gram‐
725 mar::peg.
726 tree Takes any serialized tree (per package struct::tree) as
728 input and writes it out in a generic indented format.
729 Transformation
731 mecpu Takes an abstract syntax tree for a parsing expression
733 grammer as input, generates symbolic assembler code for
734 the MatchEngine CPU, and returns that as its result (See
735 the package grammar::me::cpu and relatives).
736 reachable
738 Takes an abstract syntax tree for a parsing expression
739 grammer as input, performs a reachability analysis, and
740 returns the modified and annotated tree.
741 realizable
743 Takes an abstract syntax tree for a parsing expression
744 grammer as input, performs an analysis of realizability,
745 and returns the modified and annotated tree.
746
748 The plugin manager currently checks the plugins for only one feature,
749 timeable. A plugin supporting this feature is assumed to be able to
750 collect timing statistics on request.
751
753 This document, will undoubtedly contain bugs and other problems.
754 Please report such in the category page of the Tcllib SF Trackers
755 [http://sourceforge.net/tracker/?group_id=12883]. Please also report
756 any ideas for enhancements you may have.
757
759 page, parser generator, text processing
760
762 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
763page 1.0 page_pluginmgr(n)