1page_pluginmgr(n)           Parser generator tools           page_pluginmgr(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       page_pluginmgr - page plugin manager
9

SYNOPSIS

11       package require page::pluginmgr  ?0.2?
12
13       package require fileutil
14
15       ::page::pluginmgr::reportvia cmd
16
17       ::page::pluginmgr::report level text ?from ?to??
18
19       ::page::pluginmgr::log cmd
20
21       ::page::pluginmgr::configuration name
22
23       ::page::pluginmgr::reader name
24
25       ::page::pluginmgr::rconfigure dict
26
27       ::page::pluginmgr::rtimeable
28
29       ::page::pluginmgr::rtime
30
31       ::page::pluginmgr::rgettime
32
33       ::page::pluginmgr::rhelp
34
35       ::page::pluginmgr::rlabel
36
37       ::page::pluginmgr::read read eof ?complete?
38
39       read num
40
41       eof
42
43       done
44
45       ::page::pluginmgr::writer name
46
47       ::page::pluginmgr::wconfigure dict
48
49       ::page::pluginmgr::wtimeable
50
51       ::page::pluginmgr::wtime
52
53       ::page::pluginmgr::wgettime
54
55       ::page::pluginmgr::whelp
56
57       ::page::pluginmgr::wlabel
58
59       ::page::pluginmgr::write chan data
60
61       ::page::pluginmgr::transform name
62
63       ::page::pluginmgr::tconfigure id dict
64
65       ::page::pluginmgr::ttimeable id
66
67       ::page::pluginmgr::ttime id
68
69       ::page::pluginmgr::tgettime id
70
71       ::page::pluginmgr::thelp id
72
73       ::page::pluginmgr::tlabel id
74
75       ::page::pluginmgr::transform_do id data
76
77       page_cdefinition
78
79       page_rfeature name
80
81       page_rtime
82
83       page_rgettime
84
85       page_rlabel
86
87       page_rhelp
88
89       page_roptions
90
91       page_rconfigure option value
92
93       page_rrun
94
95       page_read num
96
97       page_read_done
98
99       page_eof
100
101       page_info text ?from ?to??
102
103       page_warning text ?from ?to??
104
105       page_error text ?from ?to??
106
107       page_log_info text
108
109       page_log_warning text
110
111       page_log_error text
112
113       page_wfeature
114
115       page_wtime
116
117       page_wgettime
118
119       page_wlabel
120
121       page_whelp
122
123       page_woptions
124
125       page_wconfigure option value
126
127       page_wrun chan data
128
129       page_info text ?from ?to??
130
131       page_warning text ?from ?to??
132
133       page_error text ?from ?to??
134
135       page_log_info text
136
137       page_log_warning text
138
139       page_log_error text
140
141       page_tfeature
142
143       page_ttime
144
145       page_tgettime
146
147       page_tlabel
148
149       page_thelp
150
151       page_toptions
152
153       page_tconfigure option value
154
155       page_trun chan data
156
157       page_info text ?from ?to??
158
159       page_warning text ?from ?to??
160
161       page_error text ?from ?to??
162
163       page_log_info text
164
165       page_log_warning text
166
167       page_log_error text
168
169______________________________________________________________________________
170

DESCRIPTION

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
177       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
184       [1]    CONFIG PLUGIN API
185
186       [2]    READER PLUGIN API
187
188       [3]    WRITER PLUGIN API
189
190       [4]    TRANSFORM PLUGIN API
191
192       as per their type.
193

API

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
201       ::page::pluginmgr::report level text ?from ?to??
202              This command is used to report input errors and warnings. By de‐
203              fault  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
207              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
211              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
216       ::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
222              Note: The cmd has to be created by the logger package, or follow
223              the same API as such.
224
225              The command returns the empty string as its result.
226
227       ::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
231              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
237              See section CONFIG PLUGIN API for the API expected of configura‐
238              tion plugins.
239
240              The result of the command is the list of options retrieved.
241
242       ::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
247              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
251              See section READER PLUGIN API for the  API  expected  of  reader
252              plugins.
253
254       ::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
259       ::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
265       ::page::pluginmgr::rtime
266              This command activates the collection of  timing  statistics  in
267              the loaded reader plugin.
268
269       ::page::pluginmgr::rgettime
270              This  command  retrieves  the collected timing statistics of the
271              loaded reader plugin after it was executed.
272
273       ::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
277       ::page::pluginmgr::rlabel
278              This  command  retrieves  the  human-readable name of the loaded
279              reader plugin.
280
281       ::page::pluginmgr::read read eof ?complete?
282              This command invokes the loaded reader plugin to process the in‐
283              put,  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
289              The  plugin  will  invoke the various callbacks in the following
290              situations:
291
292              read num
293                     is invoked whenever input to process is needed, with  the
294                     number of characters/bytes it asks for. The result is ex‐
295                     pected to be the input the plugin is in need of.
296
297              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
302              done   is  invoked  when the plugin has completed the processing
303                     of the input.
304
305       ::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
310              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
314              See section WRITER PLUGIN API for the  API  expected  of  writer
315              plugins.
316
317       ::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
322       ::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
328       ::page::pluginmgr::wtime
329              This command activates the collection of  timing  statistics  in
330              the loaded writer plugin.
331
332       ::page::pluginmgr::wgettime
333              This  command  retrieves  the collected timing statistics of the
334              loaded writer plugin after it was executed.
335
336       ::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
340       ::page::pluginmgr::wlabel
341              This  command  retrieves  the  human-readable name of the loaded
342              writer plugin.
343
344       ::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
350       ::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
356              Multiple transformations plugins can be loaded and  are  identi‐
357              fied by handles.
358
359              See  section TRANSFORM PLUGIN API for the API expected of trans‐
360              formation plugins.
361
362       ::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
367       ::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
373       ::page::pluginmgr::ttime id
374              This  command  activates  the collection of timing statistics in
375              the identified transformation plugin.
376
377       ::page::pluginmgr::tgettime id
378              This command retrieves the collected timing  statistics  of  the
379              identified transformation plugin after it was executed.
380
381       ::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
385       ::page::pluginmgr::tlabel id
386              This command retrieves the human-readable name of the identified
387              transformation plugin.
388
389       ::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  re‐
392              sult of the command.
393

CONFIG PLUGIN API

395       Configuration  plugins  are  expected  to provide a single command, de‐
396       scribed below.
397
398       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
403       Configuration plugins do not expect the environment to provide any spe‐
404       cial commands.
405
406       It  is  expected  that a configuration plugin FOO is implemented by the
407       package page::config::FOO.
408
409       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

READER PLUGIN API

414       Reader plugins are expected to  provide  the  following  commands,  de‐
415       scribed below.
416
417       page_rfeature name
418              This command takes a feature name and returns a boolean flag in‐
419              dicating whether the feature is supported by the plugin, or not.
420              The result has to be true if the feature is supported, and false
421              otherwise.
422
423              See section FEATURES for the possible features the  plugin  man‐
424              ager will ask for.
425
426       page_rtime
427              This  command  is  invoked  to activate the collection of timing
428              statistics.
429
430       page_rgettime
431              This command is invoked to retrieve the collected timing statis‐
432              tics.
433
434       page_rlabel
435              This  command  is invoked to retrieve a human-readable label for
436              the plugin.
437
438       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
442       page_roptions
443              This  command  is  invoked to retrieve the options understood by
444              the plugin.
445
446       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
450       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 re‐
453              sult of the processing.
454
455       Reader  plugins expect the environment to provide the following special
456       commands.
457
458       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
462       page_read_done
463              This  command is invoked to signal that the plugin has completed
464              the processing of the input.
465
466       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 in‐
469              put has reached the end, false otherwise.
470
471       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
477       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
482       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
487       page_log_info text
488              Invoked to report some internal information.
489
490       page_log_warning text
491              Invoked to report an internal warning.
492
493       page_log_error text
494              Invoked to report an internal error.
495
496       It  is  expected that a reader plugin FOO is implemented by the package
497       page::reader::FOO.
498
499       Reader plugins are loaded by the command ::page::pluginmgr::reader.  At
500       most one reader plugin can be kept in memory.
501

WRITER PLUGIN API

503       Writer  plugins  are  expected  to  provide the following commands, de‐
504       scribed below.
505
506       page_wfeature
507              This command takes a feature name and returns a boolean flag in‐
508              dicating whether the feature is supported by the plugin, or not.
509              The result has to be true if the feature is supported, and false
510              otherwise.
511
512              See  section  FEATURES for the possible features the plugin man‐
513              ager will ask for.
514
515       page_wtime
516              This command is invoked to activate  the  collection  of  timing
517              statistics.
518
519       page_wgettime
520              This command is invoked to retrieve the collected timing statis‐
521              tics.
522
523       page_wlabel
524              This command is invoked to retrieve a human-readable  label  for
525              the plugin.
526
527       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
531       page_woptions
532              This command is invoked to retrieve the  options  understood  by
533              the plugin.
534
535       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
539       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
545       Writer  plugins expect the environment to provide the following special
546       commands.
547
548       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
554       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
559       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
564       page_log_info text
565              Invoked to report some internal information.
566
567       page_log_warning text
568              Invoked to report an internal warning.
569
570       page_log_error text
571              Invoked to report an internal error.
572
573       It  is  expected that a writer plugin FOO is implemented by the package
574       page::writer::FOO.
575
576       Writer plugins are loaded by the command ::page::pluginmgr::writer.  At
577       most one writer plugin can be kept in memory.
578

TRANSFORM PLUGIN API page::transform::*

580       Transformation  plugins are expected to provide the following commands,
581       described below.
582
583       page_tfeature
584              This command takes a feature name and returns a boolean flag in‐
585              dicating whether the feature is supported by the plugin, or not.
586              The result has to be true if the feature is supported, and false
587              otherwise.
588
589              See  section  FEATURES for the possible features the plugin man‐
590              ager will ask for.
591
592       page_ttime
593              This command is invoked to activate  the  collection  of  timing
594              statistics.
595
596       page_tgettime
597              This command is invoked to retrieve the collected timing statis‐
598              tics.
599
600       page_tlabel
601              This command is invoked to retrieve a human-readable  label  for
602              the plugin.
603
604       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
608       page_toptions
609              This command is invoked to retrieve the  options  understood  by
610              the plugin.
611
612       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
616       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
622       Transformation  plugins expect the environment to provide the following
623       special commands.
624
625       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
631       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
636       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
641       page_log_info text
642              Invoked to report some internal information.
643
644       page_log_warning text
645              Invoked to report an internal warning.
646
647       page_log_error text
648              Invoked to report an internal error.
649
650       It  is  expected that a transformation plugin FOO is implemented by the
651       package page::transform::FOO.
652
653       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

PREDEFINED PLUGINS

658       The following predefined plugins are known, i.e. provided by  the  page
659       module.
660
661       Configuration
662
663              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
668       Reader
669
670              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
675              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
679              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
683              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
688              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
693       Writer
694
695              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
699              identity
700                     Takes any input and writes it as is.
701
702              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
706              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
711              null   Takes  any  input and writes nothing. The logical equiva‐
712                     lent of /dev/null.
713
714              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
718              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
722              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
727              tree   Takes  any  serialized tree (per package struct::tree) as
728                     input and writes it out in a generic indented format.
729
730       Transformation
731
732              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
737              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
742              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

FEATURES

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

BUGS, IDEAS, FEEDBACK

753       This  document,  and the package it describes, will undoubtedly contain
754       bugs and other problems.  Please report such in the  category  page  of
755       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
756       also report any ideas for enhancements you may have for either  package
757       and/or documentation.
758
759       When proposing code changes, please provide unified diffs, i.e the out‐
760       put of diff -u.
761
762       Note further that  attachments  are  strongly  preferred  over  inlined
763       patches.  Attachments  can  be  made  by  going to the Edit form of the
764       ticket immediately after its creation, and  then  using  the  left-most
765       button in the secondary navigation bar.
766

KEYWORDS

768       page, parser generator, text processing
769

CATEGORY

771       Page Parser Generator
772
774       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
775
776
777
778
779tcllib                                1.0                    page_pluginmgr(n)
Impressum