page_pluginmgr(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

✨ NAME ✨

Okay so bestie, meet page_pluginmgr(n) — the page plugin manager 💖. It's chillin' in the Parser generator tools corner of the manual, and it's the one holding down the whole plugin-manager situation for the page application. No cap.

🦋 SYNOPSIS 🦋

Here's the whole summoning circle, exactly as written. Don't skip a line, because every single one is doing something:

package require page::pluginmgr ?0.3?

package require fileutil

::page::pluginmgr::reportvia cmd

::page::pluginmgr::report level text ?from ?to??

::page::pluginmgr::log cmd

::page::pluginmgr::configuration name

::page::pluginmgr::reader name

::page::pluginmgr::rconfigure dict

::page::pluginmgr::rtimeable

::page::pluginmgr::rtime

::page::pluginmgr::rgettime

::page::pluginmgr::rhelp

::page::pluginmgr::rlabel

::page::pluginmgr::read read eof ?complete?

read num

eof

done

::page::pluginmgr::writer name

::page::pluginmgr::wconfigure dict

::page::pluginmgr::wtimeable

::page::pluginmgr::wtime

::page::pluginmgr::wgettime

::page::pluginmgr::whelp

::page::pluginmgr::wlabel

::page::pluginmgr::write chan data

::page::pluginmgr::transform name

::page::pluginmgr::tconfigure id dict

::page::pluginmgr::ttimeable id

::page::pluginmgr::ttime id

::page::pluginmgr::tgettime id

::page::pluginmgr::thelp id

::page::pluginmgr::tlabel id

::page::pluginmgr::transform_do id data

page_cdefinition

page_rfeature name

page_rtime

page_rgettime

page_rlabel

page_rhelp

page_roptions

page_rconfigure option value

page_rrun

page_read num

page_read_done

page_eof

page_info text ?from ?to??

page_warning text ?from ?to??

page_error text ?from ?to??

page_log_info text

page_log_warning text

page_log_error text

page_wfeature

page_wtime

page_wgettime

page_wlabel

page_whelp

page_woptions

page_wconfigure option value

page_wrun chan data

page_info text ?from ?to??

page_warning text ?from ?to??

page_error text ?from ?to??

page_log_info text

page_log_warning text

page_log_error text

page_tfeature

page_ttime

page_tgettime

page_tlabel

page_thelp

page_toptions

page_tconfigure option value

page_trun chan data

page_info text ?from ?to??

page_warning text ?from ?to??

page_error text ?from ?to??

page_log_info text

page_log_warning text

page_log_error text

💅 DESCRIPTION 💅

Okay so this package? It's literally the plugin manager at the center of the page application 👑. It manages all the various reader, writer, configuration, and transformation plugins that actually process the text — you know, the read, transform, and write of it all. Main character energy fr fr.

All plugins get loaded into slave interpreters that are specially prepared just for them ✨. And yes, they're implemented using packages, but they need this special environment, so they are not usable in a plain interpreter, like tclsh. That's the whole catch. Because of that, they're only described in general terms in the PREDEFINED PLUGINS section, and they are not documented as regular packages. The expectation is that they follow the APIs specified in these sections:

  • [1] CONFIG PLUGIN API
  • [2] READER PLUGIN API
  • [3] WRITER PLUGIN API
  • [4] TRANSFORM PLUGIN API

...as per their type, bestie. Periodt. 💅

✨ API ✨

okay so here's the whole API, every command, no skips. you're gonna eat this up 💖

  • ::page::pluginmgr::reportvia cmd — this command defines the callback command that ::page::pluginmgr::report (scroll down bestie) uses to report input errors and warnings. the default is to write those reports straight to the standard error channel. periodt.
  • ::page::pluginmgr::report level text ?from ?to?? — this is the one that reports input errors and warnings. by default it writes them to standard error. you can change that by setting a user-specific callback command with ::page::pluginmgr::reportvia (see above, queen).

the arguments level and text tell you how important the message is and what the message actually says. for the allowed values of level, go check the package logger.

the optional from and to args let the caller point at the location (or range) in the input where the reported problem occurred. each one is a list with two elements: the line and the column in the input, in that order.

  • ::page::pluginmgr::log cmd — this defines a log callback command that loaded plugins use to report internal errors, warnings, and general info. if you set the callback to the empty string, logging gets disabled. note: the cmd has to be created by the logger package, or at least follow the same API as one. the command returns the empty string as its result.
  • ::page::pluginmgr::configuration name — this loads the named configuration plugin, grabs the options encoded in it, then immediately unloads it again. if name is a path to a file, then that file gets tried as a plugin first, and if that fails, it's opened and its contents are read as a list of options and their arguments, separated by spaces, tabs and newlines, possibly quoted with single and double quotes. see the CONFIG PLUGIN API section for what configuration plugins are expected to do. the result is the list of options retrieved.
  • ::page::pluginmgr::reader name — loads the named reader plugin and initializes it. the result is a list of options the plugin understands. only one reader plugin can be loaded at a time. loading another one causes the previously loaded reader plugin to be de-initialized and unloaded. see the READER PLUGIN API section for the API expected of reader plugins.
  • ::page::pluginmgr::rconfigure dict — configures the loaded reader plugin. options and their values come in as a Tcl dictionary. result is the empty string.
  • ::page::pluginmgr::rtimeable — checks if the loaded reader plugin can collect timing statistics. result is a boolean flag: true if it can be timed, false otherwise.
  • ::page::pluginmgr::rtime — activates the collection of timing statistics in the loaded reader plugin.
  • ::page::pluginmgr::rgettime — retrieves the collected timing statistics of the loaded reader plugin after it was executed.
  • ::page::pluginmgr::rhelp — retrieves the help string of the loaded reader plugin. it's expected to be in doctools format.
  • ::page::pluginmgr::rlabel — retrieves the human-readable name of the loaded reader plugin.
  • ::page::pluginmgr::read read eof ?complete? — invokes the loaded reader plugin to process the input, and returns the plugin's results as its own result. the input is accessible through the callback commands read and eof. the optional done can be used to intercept when the plugin has completed its processing. all arguments are command prefixes. the plugin will invoke the various callbacks in these situations:
    • read num — 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.
    • eof — invoked by the plugin to check if the input has reached the end of the stream. the result is expected to be a boolean flag: true when the input has hit EOF, false otherwise.
    • done — invoked when the plugin has completed processing the input.
  • ::page::pluginmgr::writer name — loads the named writer plugin and initializes it. the result is a list of options the plugin understands. only a single reader plugin can be loaded. loading another reader plugin causes the previously loaded reader plugin to be de-initialized and unloaded. see the WRITER PLUGIN API section for the API expected of writer plugins.
bestie, yes that says "reader" under the writer command. that's literally what the original says, so I'm keeping it. no cap. 😭
  • ::page::pluginmgr::wconfigure dict — configures the loaded writer plugin. options and their values come in as a Tcl dictionary. result is the empty string.
  • ::page::pluginmgr::wtimeable — checks if the loaded writer plugin can measure execution times. result is a boolean flag: true if it can be timed, false otherwise.
  • ::page::pluginmgr::wtime — activates the collection of timing statistics in the loaded writer plugin.
  • ::page::pluginmgr::wgettime — retrieves the collected timing statistics of the loaded writer plugin after it was executed.
  • ::page::pluginmgr::whelp — retrieves the help string of the loaded writer plugin. expected to be in doctools format.
  • ::page::pluginmgr::wlabel — retrieves the human-readable name of the loaded writer plugin.
  • ::page::pluginmgr::write chan data — invokes the loaded writer plugin to generate the output. it gets the data to generate the output from, and the Tcl handle chan of the channel to write the generated output to. the command returns the empty string as its result.
  • ::page::pluginmgr::transform name — loads the named transformation plugin and initializes it. the result is a 2-element list containing the plugin id and a list of options the plugin understands, in that order. multiple transformation plugins can be loaded and are identified by handles. see the TRANSFORM PLUGIN API section for the API expected of transformation plugins.
  • ::page::pluginmgr::tconfigure id dict — configures the identified transformation plugin. options and their values come in as a Tcl dictionary. result is the empty string.
  • ::page::pluginmgr::ttimeable id — checks if the identified transformation plugin can collect timing statistics. result is a boolean flag: true if it can be timed, false otherwise.
  • ::page::pluginmgr::ttime id — activates the collection of timing statistics in the identified transformation plugin.
  • ::page::pluginmgr::tgettime id — retrieves the collected timing statistics of the identified transformation plugin after it was executed.
  • ::page::pluginmgr::thelp id — retrieves the help string of the identified transformation plugin. expected to be in doctools format.
  • ::page::pluginmgr::tlabel id — retrieves the human-readable name of the identified transformation plugin.
  • ::page::pluginmgr::transform_do id data — invokes the identified transformation plugin to process the specified data. the result of the plugin is returned as the result of the command.

🎀 CONFIG PLUGIN API 🎀

configuration plugins are expected to provide a single command, described below. slay.

  • page_cdefinition — this command of a configuration plugin is called by the plugin manager to execute it. its result has to be a list of options and values to process.

configuration plugins do not expect the environment to provide any special commands.

it's expected that a configuration plugin FOO is implemented by the package page::config::FOO.

configuration plugins are loaded, executed, and unloaded in one step. they are not kept in memory. the command for doing this is ::page::pluginmgr::configuration.

🦋 READER PLUGIN API 🦋

Okay bestie, if you're building a reader plugin, here's the whole vibe: it's expected to hand over these commands, and we're gonna walk through every single one because we don't skip. 💅

  • page_rfeature name — you pass in a feature name and it returns a boolean flag saying whether the plugin supports that feature or not, periodt. The result has to be true if it's supported, and false if it isn't. That's the whole assignment.
Peep the FEATURES section for the actual list of features the plugin manager is gonna come asking about. 👀
  • page_rtime — invoked to activate the collection of timing statistics. Stats girlies rise up. ✨
  • page_rgettime — invoked to retrieve the collected timing statistics. Get those numbers back.
  • page_rlabel — invoked to retrieve a human-readable label for the plugin. Something cute for the people. 🎀
  • page_rhelp — invoked to retrieve a help text for the plugin. Heads up: that text is expected to be in doctools format.
  • page_roptions — invoked to retrieve the options understood by the plugin.
  • page_rconfigure option value — invoked to reconfigure the plugin. Specifically: the given option gets set to the new value. Glow-up moment. 💖
  • page_rrun — invoked to process the input stream according to the plugin's current configuration. And the result of the command is the result of the processing. No cap.

Reader plugins also expect the environment to have their back with these special commands, okay? Like the environment is the bestie that shows up with snacks. 🫶

  • page_read num — invoked to read num characters/bytes from the input. Its result has to be the read characters/bytes.
  • page_read_done — invoked to signal that the plugin has completed processing the input. You did it, congrats. 🎉
  • page_eof — invoked to check if the input stream has reached its end. Its result has to be a boolean flag: true when the input has reached the end, false otherwise.
  • page_info text ?from ?to?? — 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.
  • page_warning text ?from ?to?? — 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.
  • page_error text ?from ?to?? — 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.
  • page_log_info text — invoked to report some internal information.
  • page_log_warning text — invoked to report an internal warning.
  • page_log_error text — invoked to report an internal error.

So here's the tea: a reader plugin named FOO is expected to be implemented by the package page::reader::FOO. Cute, right? 😌

And reader plugins get loaded by the command ::page::pluginmgr::reader. Key detail: at most one reader plugin can be kept in memory at a time. One. Singular. 💀

💜 WRITER PLUGIN API 💜

Now for the writer girlies — writer plugins are expected to provide these commands, described below. Same energy, different letter. Let's go. 🌈

  • page_wfeature — this command takes a feature name and returns a boolean flag indicating whether the feature is supported by the plugin, or not. The result has to be true if the feature is supported, and false otherwise.
Again, see the FEATURES section for the possible features the plugin manager will ask for. 🔥
  • page_wtime — invoked to activate the collection of timing statistics.
  • page_wgettime — invoked to retrieve the collected timing statistics.
  • page_wlabel — invoked to retrieve a human-readable label for the plugin.
  • page_whelp — invoked to retrieve a help text for the plugin. The text is expected to be in doctools format.
  • page_woptions — invoked to retrieve the options understood by the plugin.
  • page_wconfigure option value — invoked to reconfigure the plugin. Specifically: the given option is set to the new value.
  • page_wrun chan data — invoked to process the specified data and write it to the output stream chan. That chan is a Tcl channel handle opened for writing. The result of the command is the empty string. 🫧

Writer plugins expect the environment to provide these special commands too:

  • page_info text ?from ?to?? — 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.
  • page_warning text ?from ?to?? — 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.
  • page_error text ?from ?to?? — 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.
  • page_log_info text — invoked to report some internal information.
  • page_log_warning text — invoked to report an internal warning.
  • page_log_error text — invoked to report an internal error.

A writer plugin named FOO is expected to be implemented by the package page::writer::FOO. Iconic naming convention, honestly. 👑

Writer plugins are loaded by the command ::page::pluginmgr::writer. And once again: at most one writer plugin can be kept in memory. Just the one. 🙈

✨ TRANSFORM PLUGIN API page::transform::* ✨

Transformation plugins — the glow-up girlies of the pipeline — are expected to provide these commands, described below.

  • page_tfeature — this command takes a feature name and returns a boolean flag indicating whether the feature is supported by the plugin, or not. The result has to be true if the feature is supported, and false otherwise.
See the FEATURES section for the possible features the plugin manager will ask for. ⭐
  • page_ttime — invoked to activate the collection of timing statistics.
  • page_tgettime — invoked to retrieve the collected timing statistics.
  • page_tlabel — invoked to retrieve a human-readable label for the plugin.
  • page_thelp — invoked to retrieve a help text for the plugin. The text is expected to be in doctools format.
  • page_toptions — invoked to retrieve the options understood by the plugin.
  • page_tconfigure option value — invoked to reconfigure the plugin. Specifically: the given option is set to the new value.
  • page_trun chan data — invoked to process the specified data and write it to the output stream chan. That chan is a Tcl channel handle opened for writing. The result of the command is the empty string. 🧚

Transformation plugins expect the environment to provide these special commands:

  • page_info text ?from ?to?? — 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.
  • page_warning text ?from ?to?? — 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.
  • page_error text ?from ?to?? — 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.
  • page_log_info text — invoked to report some internal information.
  • page_log_warning text — invoked to report an internal warning.
  • page_log_error text — invoked to report an internal error.

A transformation plugin named FOO is expected to be implemented by the package page::transform::FOO. Consistent queen behavior. 💅

Transformation plugins are loaded by the command ::page::pluginmgr::transform. And here's the fun part — unlike the reader and writer girlies, more than one transformation plugin can be kept in memory. Plural. Stack 'em up. 🌸

✨ PREDEFINED PLUGINS ✨

okay so these are the plugins that ship with the box, like they're already there, provided by the page module itself, no extra setup bestie 🎀

Configuration 🛠️

  • peg — hands you back a whole set of options that configure the page application for chewing through a PEG grammar and spitting out ME code. If you wanna know the lore, go peek at the packages grammar_peg, grammar_me and relations 👑

Reader 📖

  • hb — expects a so-called half-baked PEG container as input and gives you back the equivalent abstract syntax tree. The writer plugin hb is the one that makes this kind of input, iykyk 🦋
  • lemon — expects a grammar spec like the one Richar Hipp's LEMON parser generator understands, and returns an abstract syntax tree for it 🍋
  • peg — expects a grammar spec written as a parsing expression grammar (PEG) and returns an abstract syntax tree for it 💅
  • ser — expects the serialized form of a parsing expression grammar (the kind the package grammar::peg generates) as input, converts it into an equivalent abstract syntax tree, and returns that ✨
  • treeser — expects the serialized form of a tree (the kind the package struct::tree generates) as input, validates it, and returns it 🌸

Writer ✍️

  • hb — expects an abstract syntax tree for a parsing expression grammar as input and writes it out as a so-called half-baked PEG container 🫶
  • identity — takes literally any input and writes it out exactly as is. no thoughts, head empty, just vibes 💀
  • mecpu — expects symbolic assembler code for the MatchEngine CPU (see the package grammar::me::cpu and relatives) and writes it out as Tcl code for a parser 🔥
  • me — expects an abstract syntax tree for a parsing expression grammar as input and writes it out as Tcl code for the MatchEngine (see the package grammar::me and relatives) which then parses input in that grammar 👑
  • null — takes any input and writes nothing. the logical equivalent of /dev/null, iconic behaviour honestly 🙈
  • peg — expects an abstract syntax tree for a parsing expression grammar as input and writes it out as a canonical PEG that the reader plugin peg can read right back 🌈
  • ser — expects an abstract syntax tree for a parsing expression grammar as input and writes it out as a serialized PEG container that the reader plugin ser can read right back 💜
  • tpc — expects an abstract syntax tree for a parsing expression grammar as input and writes it out as Tcl code that initializes a PEG container, the kind the package grammar::peg provides ⭐
  • tree — takes any serialized tree (per package struct::tree) as input and writes it out in a generic indented format 🎀

Transformation 🔄

  • mecpu — takes an abstract syntax tree for a parsing expression grammer as input, generates symbolic assembler code for the MatchEngine CPU, and returns that as its result (see the package grammar::me::cpu and relatives) 🔥
  • reachable — takes an abstract syntax tree for a parsing expression grammer as input, runs a reachability analysis, and returns the modified and annotated tree 🦋
  • realizable — takes an abstract syntax tree for a parsing expression grammer as input, runs an analysis of realizability, and returns the modified and annotated tree ✨

💫 FEATURES 💫

as of right now, the plugin manager only ever checks plugins for one single feature, and that feature is timeable. a plugin that supports it is assumed to be able to collect timing statistics whenever you ask for them ⏱️

😭 BUGS, IDEAS, FEEDBACK 😭

ngl bestie, this document — and the package it describes — will undoubtedly contain bugs and other problems. please report them in the category page of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. and please also drop any ideas you have for enhancements to either the package and/or the documentation, we want them fr fr 🫶

when you're proposing code changes, please give unified diffs, i.e. the output of diff -u 💅

also, heads up: attachments are strongly preferred over inlined patches. to attach something, go to the Edit form of the ticket immediately after it's created, and then use the left-most button in the secondary navigation bar 👑

🔑 KEYWORDS 🔑

page, parser generator, text processing

🗂️ CATEGORY 🗂️

Page Parser Generator

Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>

and that's the whole thing, bestie, we made it to the end 🎉 this beauty lives in tcllib, version 1.0, and it's the page_pluginmgr(n) page — go forth and manage those plugins, you absolute main character 💅✨🦋

📦 where this page comes from