1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin page_pluginmgr n 1.0] 3[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Parser generator tools}] 5[titledesc {page plugin manager}] 6[category {Page Parser Generator}] 7[keywords page {parser generator} {text processing}] 8[require page::pluginmgr [opt 0.2]] 9[require fileutil] 10[description] 11[para] 12 13This package provides the plugin manager central to the [syscmd page] 14application. It manages the various reader, writer, configuration, and 15transformation plugins which actually process the text (read, 16transform, and write). 17 18[para] 19 20All plugins are loaded into slave interpreters specially prepared for 21them. While implemented using packages they need this special 22environment and are not usable in a plain interpreter, like 23tclsh. Because of that they are only described in general terms in 24section [sectref {PREDEFINED PLUGINS}], and not documented as regular 25packages. It is expected that they follow the APIs specified in the 26sections 27 28[list_begin enum] 29[enum] [sectref {CONFIG PLUGIN API}] 30[enum] [sectref {READER PLUGIN API}] 31[enum] [sectref {WRITER PLUGIN API}] 32[enum] [sectref {TRANSFORM PLUGIN API}] 33[list_end] 34 35as per their type. 36 37[section API] 38 39[list_begin definitions] 40 41[call [cmd ::page::pluginmgr::reportvia] [arg cmd]] 42 43This command defines the callback command used by 44 45[cmd ::page::pluginmgr::report] (see below) to report input errors and 46warnings. The default is to write such reports to the standard error 47channel. 48 49[call [cmd ::page::pluginmgr::report] [arg level] [arg text] [opt "[arg from] [opt [arg to]]"]] 50 51This command is used to report input errors and warnings. By default 52such reports are written to the standard error. This can be changed by 53setting a user-specific callback command with 54[cmd ::page::pluginmgr::reportvia] (see above). 55 56[para] 57 58The arguments [arg level] and [arg text] specify both the importance 59of the message, and the message itself. For the former see the package 60[package logger] for the allowed values. 61 62[para] 63 64The optional argument [arg from] and [arg to] can be used by the 65caller to indicate the location (or range) in the input where the 66reported problem occured. Each is a list containing two elements, the 67line and the column in the input, in this order. 68 69 70[call [cmd ::page::pluginmgr::log] [arg cmd]] 71 72This command defines a log callback command to be used by loaded 73plugins for the reporting of internal errors, warnings, and general 74information. Specifying the empty string as callback disables logging. 75 76[para] 77 78Note: The [arg cmd] has to be created by the [package logger] package, 79or follow the same API as such. 80 81[para] 82 83The command returns the empty string as its result. 84 85 86[call [cmd ::page::pluginmgr::configuration] [arg name]] 87 88This command loads the named configuration plugin, retrieves the 89options encoded in it, and then immediately unloads it again. 90 91[para] 92 93If the [arg name] is the path to a file, then this files will be tried 94to be loaded as a plugin first, and, if that fails, opened and its 95contents read as a list of options and their arguments, separated by 96spaces, tabs and newlines, possibly quotes with single and double 97quotes. 98 99[para] 100 101See section [sectref {CONFIG PLUGIN API}] for the API expected of 102configuration plugins. 103 104[para] 105 106The result of the command is the list of options retrieved. 107 108 109[call [cmd ::page::pluginmgr::reader] [arg name]] 110 111This command loads the named reader plugin and initializes it. The 112result of the command is a list of options the plugin understands. 113 114[para] 115 116Only a single reader plugin can be loaded. Loading another reader 117plugin causes the previously loaded reader plugin to be de-initialized 118and unloaded. 119 120[para] 121 122See section [sectref {READER PLUGIN API}] for the API expected of 123reader plugins. 124 125 126[call [cmd ::page::pluginmgr::rconfigure] [arg dict]] 127 128This commands configures the loaded reader plugin. The options and 129their values are provided as a Tcl dictionary. The result of the 130command is the empty string. 131 132[call [cmd ::page::pluginmgr::rtimeable]] 133 134This commands checks if the loaded reader plugin is able to collect 135timing statistics. The result of the command is a boolean flag. The 136result is [const true] if the plugin can be timed, and [const false] 137otherwise. 138 139[call [cmd ::page::pluginmgr::rtime]] 140 141This command activates the collection of timing statistics in the 142loaded reader plugin. 143 144[call [cmd ::page::pluginmgr::rgettime]] 145 146This command retrieves the collected timing statistics of the loaded 147reader plugin after it was executed. 148 149[call [cmd ::page::pluginmgr::rhelp]] 150 151This command retrieves the help string of the loaded reader 152plugin. This is expected to be in [term doctools] format. 153 154[call [cmd ::page::pluginmgr::rlabel]] 155 156This command retrieves the human-readable name of the loaded reader 157plugin. 158 159[call [cmd ::page::pluginmgr::read] [arg read] [arg eof] [opt [arg complete]]] 160 161This command invokes the loaded reader plugin to process the input, 162and returns the results of the plugin as its own result. The input is 163accessible through the callback commands [arg read], and [arg eof]. The 164optional [arg done] can be used to intrecept when the plugin has 165completed its processing. All arguments are command prefixes. 166 167[para] 168 169The plugin will invoke the various callbacks in the following 170situations: 171 172[list_begin definitions] 173[call [arg read] [arg num]] 174is invoked whenever input to process is needed, with the number of 175characters/bytes it asks for. The result is expected to be the input 176the plugin is in need of. 177 178[call [arg eof]] 179is invoked by the plugin to check if the input has reached the of the 180stream. The result is expected to be a boolean flag, [const true] when 181the input has hit EOF, and [const false] otherwise. 182 183[call [arg done]] 184is invoked when the plugin has completed the processing of the input. 185 186[list_end] 187 188[call [cmd ::page::pluginmgr::writer] [arg name]] 189 190This command loads the named writer plugin and initializes it. The 191result of the command is a list of options the plugin understands. 192 193[para] 194 195Only a single reader plugin can be loaded. Loading another reader 196plugin causes the previously loaded reader plugin to be de-initialized 197and unloaded. 198 199[para] 200 201See section [sectref {WRITER PLUGIN API}] for the API expected of 202writer plugins. 203 204[call [cmd ::page::pluginmgr::wconfigure] [arg dict]] 205 206This commands configures the loaded writer plugin. The options and 207their values are provided as a Tcl dictionary. The result of the 208command is the empty string. 209 210[call [cmd ::page::pluginmgr::wtimeable]] 211 212This commands checks if the loaded writer plugin is able to measure 213execution times. The result of the command is a boolean flag. The 214result is [const true] if the plugin can be timed, and [const false] 215otherwise. 216 217[call [cmd ::page::pluginmgr::wtime]] 218 219This command activates the collection of timing statistics in the 220loaded writer plugin. 221 222[call [cmd ::page::pluginmgr::wgettime]] 223 224This command retrieves the collected timing statistics of the loaded 225writer plugin after it was executed. 226 227[call [cmd ::page::pluginmgr::whelp]] 228 229This command retrieves the help string of the loaded writer 230plugin. This is expected to be in [term doctools] format. 231 232[call [cmd ::page::pluginmgr::wlabel]] 233 234This command retrieves the human-readable name of the loaded writer 235plugin. 236 237[call [cmd ::page::pluginmgr::write] [arg chan] [arg data]] 238 239The loaded writer plugin is invoked to generate the output. It is 240given the [arg data] to generate the outpout from, and the Tcl handle 241[arg chan] of the channel to write the generated output to. The 242command returns th empty string as its result. 243 244[call [cmd ::page::pluginmgr::transform] [arg name]] 245 246This command loads the named transformation plugin and initializes 247it. The result of the command is a 2-element list containing the 248plugin id and a list of options the plugin understands, in this order. 249 250[para] 251 252Multiple transformations plugins can be loaded and are identified by 253handles. 254 255[para] 256 257See section [sectref {TRANSFORM PLUGIN API}] for the API expected of 258transformation plugins. 259 260[call [cmd ::page::pluginmgr::tconfigure] [arg id] [arg dict]] 261 262This commands configures the identified transformation plugin. The 263options and their values are provided as a Tcl dictionary. The result 264of the command is the empty string. 265 266[call [cmd ::page::pluginmgr::ttimeable] [arg id]] 267 268This commands checks if the identified transformation plugin is able 269to collect timing statistics. The result of the command is a boolean 270flag. The result is [const true] if the plugin can be timed, and 271[const false] otherwise. 272 273[call [cmd ::page::pluginmgr::ttime] [arg id]] 274 275This command activates the collection of timing statistics in the 276identified transformation plugin. 277 278[call [cmd ::page::pluginmgr::tgettime] [arg id]] 279 280This command retrieves the collected timing statistics of the 281identified transformation plugin after it was executed. 282 283[call [cmd ::page::pluginmgr::thelp] [arg id]] 284 285This command retrieves the help string of the identified 286transformation plugin. This is expected to be in [term doctools] 287format. 288 289[call [cmd ::page::pluginmgr::tlabel] [arg id]] 290 291This command retrieves the human-readable name of the identified 292transformation plugin. 293 294[call [cmd ::page::pluginmgr::transform_do] [arg id] [arg data]] 295 296The identified transformation plugin is invoked to process the 297specified [arg data]. The result of the plugin is returned as the 298result of the command. 299 300[list_end] 301 302[section {CONFIG PLUGIN API}] 303 304Configuration plugins are expected to provide a single command, 305described below. 306 307[para] 308 309[list_begin definitions] 310[call [cmd page_cdefinition]] 311 312This command of a configuration plugin is called by the plugin manager 313to execute it. Its result has to be a list of options and values to 314process. 315 316[list_end] 317[para] 318 319Configuration plugins do not expect the environment to provide any 320special commands. 321 322[para] 323 324It is expected that a configuration plugin [const FOO] is implemented 325by the package [package page::config::[const FOO]]. 326 327[para] 328 329Configuration plugins are loaded, executed, and unloaded in one step, 330they are not kept in memory. The command for doing this is 331[cmd ::page::pluginmgr::configuration]. 332 333[section {READER PLUGIN API}] 334 335Reader plugins are expected to provide the following commands, 336described below. 337 338[para] 339 340[list_begin definitions] 341 342[call [cmd page_rfeature] [arg name]] 343 344This command takes a feature [arg name] and returns a boolean flag 345indicating whether the feature is supported by the plugin, or not. 346 347The result has to be [const true] if the feature is supported, and 348[const false] otherwise. 349 350[para] 351 352See section [sectref FEATURES] for the possible features the plugin 353manager will ask for. 354 355[call [cmd page_rtime]] 356 357This command is invoked to activate the collection of timing 358statistics. 359 360[call [cmd page_rgettime]] 361 362This command is invoked to retrieve the collected timing statistics. 363 364[call [cmd page_rlabel]] 365 366This command is invoked to retrieve a human-readable label for the 367plugin. 368 369[call [cmd page_rhelp]] 370 371This command is invoked to retrieve a help text for plugin. The text 372is expected to be in [term doctools] format. 373 374[call [cmd page_roptions]] 375 376This command is invoked to retrieve the options understood by the 377plugin. 378 379[call [cmd page_rconfigure] [arg option] [arg value]] 380 381This command is invoked to reconfigure the plugin, specifically the 382given [arg option] is set to the new [arg value]. 383 384[call [cmd page_rrun]] 385 386This command is invoked to process the input stream per the current 387plugin configuration. The result of the command is the result of the 388processing. 389 390[list_end] 391[para] 392 393Reader plugins expect the environment to provide the following special 394commands. 395 396[list_begin definitions] 397 398[call [cmd page_read] [arg num]] 399 400This command is invoked to read [arg num] characters/bytes from the 401input. Its result has to be read characters/bytes. 402 403[call [cmd page_read_done]] 404 405This command is invoked to signal that the plugin has completed the 406processing of the input. 407 408[call [cmd page_eof]] 409 410This command is invoked to check if the input stream has reached its 411end. Its result has to be a boolean flag, [const true] when the input 412has reached the end, [const false] otherwise. 413 414[call [cmd page_info] [arg text] [opt "[arg from] [opt [arg to]]"]] 415 416Invoked to report some information to the user. May indicate a 417location or range in the input. Each piece of location data, if 418provided, is a 2-element list containing line and column numbers. 419 420[call [cmd page_warning] [arg text] [opt "[arg from] [opt [arg to]]"]] 421 422Invoked to report a warning to the user. May indicate a location or 423range in the input. Each piece of location data, if provided, is a 4242-element list containing line and column numbers. 425 426[call [cmd page_error] [arg text] [opt "[arg from] [opt [arg to]]"]] 427 428Invoked to report an error to the user. May indicate a location or 429range in the input. Each piece of location data, if provided, is a 4302-element list containing line and column numbers. 431 432[call [cmd page_log_info] [arg text]] 433 434Invoked to report some internal information. 435 436[call [cmd page_log_warning] [arg text]] 437 438Invoked to report an internal warning. 439 440[call [cmd page_log_error] [arg text]] 441 442Invoked to report an internal error. 443 444[list_end] 445[para] 446 447It is expected that a reader plugin [const FOO] is implemented 448by the package [package page::reader::[const FOO]]. 449 450[para] 451 452Reader plugins are loaded by the command 453[cmd ::page::pluginmgr::reader]. At most one reader plugin can be kept 454in memory. 455 456[section {WRITER PLUGIN API}] 457 458Writer plugins are expected to provide the following commands, 459described below. 460 461[para] 462 463[list_begin definitions] 464 465[call [cmd page_wfeature]] 466 467This command takes a feature [arg name] and returns a boolean flag 468indicating whether the feature is supported by the plugin, or not. 469 470The result has to be [const true] if the feature is supported, and 471[const false] otherwise. 472 473[para] 474 475See section [sectref FEATURES] for the possible features the plugin 476manager will ask for. 477 478[call [cmd page_wtime]] 479 480This command is invoked to activate the collection of timing 481statistics. 482 483[call [cmd page_wgettime]] 484 485This command is invoked to retrieve the collected timing statistics. 486 487[call [cmd page_wlabel]] 488 489This command is invoked to retrieve a human-readable label for the 490plugin. 491 492[call [cmd page_whelp]] 493 494This command is invoked to retrieve a help text for plugin. The text 495is expected to be in [term doctools] format. 496 497[call [cmd page_woptions]] 498 499This command is invoked to retrieve the options understood by the 500plugin. 501 502[call [cmd page_wconfigure] [arg option] [arg value]] 503 504This command is invoked to reconfigure the plugin, specifically the 505given [arg option] is set to the new [arg value]. 506 507[call [cmd page_wrun] [arg chan] [arg data]] 508 509This command is invoked to process the specified [arg data] and write 510it to the output stream [arg chan]. The latter is a Tcl channel handle 511opened for writing. The result of the command is the empty string. 512 513[list_end] 514[para] 515 516Writer plugins expect the environment to provide the following special 517commands. 518 519[list_begin definitions] 520 521[call [cmd page_info] [arg text] [opt "[arg from] [opt [arg to]]"]] 522 523Invoked to report some information to the user. May indicate a 524location or range in the input. Each piece of location data, if 525provided, is a 2-element list containing line and column numbers. 526 527[call [cmd page_warning] [arg text] [opt "[arg from] [opt [arg to]]"]] 528 529Invoked to report a warning to the user. May indicate a location or 530range in the input. Each piece of location data, if provided, is a 5312-element list containing line and column numbers. 532 533[call [cmd page_error] [arg text] [opt "[arg from] [opt [arg to]]"]] 534 535Invoked to report an error to the user. May indicate a location or 536range in the input. Each piece of location data, if provided, is a 5372-element list containing line and column numbers. 538 539[call [cmd page_log_info] [arg text]] 540 541Invoked to report some internal information. 542 543[call [cmd page_log_warning] [arg text]] 544 545Invoked to report an internal warning. 546 547[call [cmd page_log_error] [arg text]] 548 549Invoked to report an internal error. 550 551[list_end] 552[para] 553 554It is expected that a writer plugin [const FOO] is implemented 555by the package [package page::writer::[const FOO]]. 556 557[para] 558 559Writer plugins are loaded by the command 560[cmd ::page::pluginmgr::writer]. At most one writer plugin can be kept 561in memory. 562 563[section {TRANSFORM PLUGIN API}] page::transform::* 564 565Transformation plugins are expected to provide the following commands, 566described below. 567 568[para] 569 570[list_begin definitions] 571 572[call [cmd page_tfeature]] 573 574This command takes a feature [arg name] and returns a boolean flag 575indicating whether the feature is supported by the plugin, or not. 576 577The result has to be [const true] if the feature is supported, and 578[const false] otherwise. 579 580[para] 581 582See section [sectref FEATURES] for the possible features the plugin 583manager will ask for. 584 585[call [cmd page_ttime]] 586 587This command is invoked to activate the collection of timing 588statistics. 589 590[call [cmd page_tgettime]] 591 592This command is invoked to retrieve the collected timing statistics. 593 594[call [cmd page_tlabel]] 595 596This command is invoked to retrieve a human-readable label for the 597plugin. 598 599[call [cmd page_thelp]] 600 601This command is invoked to retrieve a help text for plugin. The text 602is expected to be in [term doctools] format. 603 604[call [cmd page_toptions]] 605 606This command is invoked to retrieve the options understood by the 607plugin. 608 609[call [cmd page_tconfigure] [arg option] [arg value]] 610 611This command is invoked to reconfigure the plugin, specifically the 612given [arg option] is set to the new [arg value]. 613 614[call [cmd page_trun] [arg chan] [arg data]] 615 616This command is invoked to process the specified [arg data] and write 617it to the output stream [arg chan]. The latter is a Tcl channel handle 618opened for writing. The result of the command is the empty string. 619 620[list_end] 621[para] 622 623Transformation plugins expect the environment to provide the following 624special commands. 625 626[list_begin definitions] 627 628[call [cmd page_info] [arg text] [opt "[arg from] [opt [arg to]]"]] 629 630Invoked to report some information to the user. May indicate a 631location or range in the input. Each piece of location data, if 632provided, is a 2-element list containing line and column numbers. 633 634[call [cmd page_warning] [arg text] [opt "[arg from] [opt [arg to]]"]] 635 636Invoked to report a warning to the user. May indicate a location or 637range in the input. Each piece of location data, if provided, is a 6382-element list containing line and column numbers. 639 640[call [cmd page_error] [arg text] [opt "[arg from] [opt [arg to]]"]] 641 642Invoked to report an error to the user. May indicate a location or 643range in the input. Each piece of location data, if provided, is a 6442-element list containing line and column numbers. 645 646[call [cmd page_log_info] [arg text]] 647 648Invoked to report some internal information. 649 650[call [cmd page_log_warning] [arg text]] 651 652Invoked to report an internal warning. 653 654[call [cmd page_log_error] [arg text]] 655 656Invoked to report an internal error. 657 658[list_end] 659[para] 660 661It is expected that a transformation plugin [const FOO] is implemented 662by the package [package page::transform::[const FOO]]. 663 664[para] 665 666Transformation plugins are loaded by the command 667 668[cmd ::page::pluginmgr::transform]. More than one transformation 669plugin can be kept in memory. 670 671[section {PREDEFINED PLUGINS}] 672 673The following predefined plugins are known, i.e. provided by the page 674module. 675 676[list_begin definitions] 677 678[def Configuration] 679[list_begin definitions] 680[def peg] 681 682Returns a set of options to configure the [syscmd page] application 683for the processing of a PEG grammar and the generation of ME code. See 684the packages [package grammar_peg], [package grammar_me] and relations 685for more details. 686 687[list_end] 688 689[def Reader] 690[list_begin definitions] 691[def hb] 692Expects a so-called [term {half-baked PEG container}] as input and 693returns the equivalent abstract syntax tree. See the writer plugin 694[term hb] for the plugin generating this type of input. 695 696[def lemon] 697Expects a grammar specification as understood by Richar Hipp's LEMON 698parser generator and returns an abstract syntax tree for it. 699 700[def peg] 701Expects a grammar specification in the form of a parsing expression 702grammar (PEG) and returns an abstract syntax tree for it. 703 704[def ser] 705Expect the serialized form of a parsing expression grammar as 706generated by the package [package grammar::peg] as input, converts it 707into an equivalent abstract syntax tree and returns that. 708 709[def treeser] 710Expects the serialized form of a tree as generated by the package 711[package struct::tree] as input and returns it, after validation. 712 713[list_end] 714 715[def Writer] 716[list_begin definitions] 717[def hb] 718Expects an abstract syntax tree for a parsing expression grammar as 719input and writes it out in the form of a so-called 720[term {half-baked PEG container}]. 721 722[def identity] 723Takes any input and writes it as is. 724 725[def mecpu] 726Expects symbolic assembler code for the MatchEngine CPU (See the 727package [package grammar::me::cpu] and relatives) and writes it out as 728Tcl code for a parser. 729 730[def me] 731Expects an abstract syntax tree for a parsing expression grammar as 732input and writes it out as Tcl code for the MatchEngine (See the 733package [package grammar::me] and relatives) which parses input in 734that grammar. 735 736[def null] 737Takes any input and writes nothing. The logical equivalent of 738/dev/null. 739 740[def peg] 741Expects an abstract syntax tree for a parsing expression grammar as 742input and writes it out in the form of a canonical PEG which can be 743read by the reader plugin [term peg]. 744 745[def ser] 746Expects an abstract syntax tree for a parsing expression grammar as 747input and writes it out as a serialized PEG container which can be 748read by the reader plugin [term ser]. 749 750[def tpc] 751Expects an abstract syntax tree for a parsing expression grammar as 752input and writes it out as Tcl code initializing a PEG container as 753provided by the package [package grammar::peg]. 754 755[def tree] 756Takes any serialized tree (per package [package struct::tree]) as 757input and writes it out in a generic indented format. 758 759[list_end] 760 761[def Transformation] 762[list_begin definitions] 763 764[def mecpu] 765Takes an abstract syntax tree for a parsing expression grammer as 766input, generates symbolic assembler code for the MatchEngine CPU, and 767returns that as its result (See the package [package grammar::me::cpu] 768and relatives). 769 770[def reachable] 771Takes an abstract syntax tree for a parsing expression grammer as 772input, performs a reachability analysis, and returns the modified and 773annotated tree. 774 775[def realizable] 776Takes an abstract syntax tree for a parsing expression grammer as 777input, performs an analysis of realizability, and returns the modified 778and annotated tree. 779 780[list_end] 781[list_end] 782 783[comment { 784 Make it clear that all data between plugins is shuffled around 785 in serialized form, as objects cannot be transfered/accessed 786 across the interpreter boundaries (safety concerns). 787 788 Describe the commands expected by plugins to be available in 789 the environment. 790 791 Describe the predefined features. 792}] 793 794 795[section FEATURES] 796 797The plugin manager currently checks the plugins for only one feature, 798[const timeable]. A plugin supporting this feature is assumed to be 799able to collect timing statistics on request. 800 801 802[section {BUGS, IDEAS, FEEDBACK}] 803 804This document, will undoubtedly contain bugs and other problems. 805 806Please report such in the category [emph page] of the 807[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 808 809Please also report any ideas for enhancements you may have. 810 811[manpage_end] 812